Kitten

Reference

About

Kitten is a little kit (“kitten”, get it?) optimised for people (not corporations) who make the new everyday things for themselves and other people – not because they want to become billionaires but because they want to contribute to the common good by helping nurture the Small Web while adhering to the Small Technology Principles.

Kitten features intuitive file system-based routing, HTML and accessibility validation, a built-in object database, WebSockets, zero-code authentication, public-key cryptography, Markdown support, syntax highlighting via highlight.js, semantic styles via Water CSS, and more.

System requirements

• Linux and macOS.
• Bash version 5.x+.
• Common developer tools and system utilities (git, tar, tee, and xz).

Installing Kitten

To install Kitten, either:

• 😇 Clone the Kitten repository and run the ./install script:

  git clone https://codeberg.org/kitten/app kitten
  cd kitten
  ./install
  

• 😈 Or, copy and paste one of the following commands into your terminal to pipe the installation script into your shell and run it:

  Using wget:

  wget -qO- https://kittens.small-web.org/install | bash
  

  Using curl:

  curl -sL https://kittens.small-web.org/install | bash
  

  Download and view the install script source to verify it’s safe to pipe to your shell.

  You can also compare it to the code in the source repository to ensure they’re the same.

  Post-installation steps (macOS)

  On macOS, you have a couple of manual post-installation steps to perform.

  (Detailed instructions on how to carry out the below steps are presented in the installer at installation time.)

  1. You must update your system’s path with the location of the kitten binary as ~/.local/bin is not on the path by default on macOS.

     (You will also have to do this on Linux distributions that don’t automatically add this folder to your system path. The installer will prompt you to do this if it detects that this is the case.)

  2. If you want to test peer-to-peer apps locally, you must edit your ~/etc/hosts file to add Kitten’s localhost aliases (place1.localhost, place2.localhost, …, place4.localhost).

  To learn more about building peer-to-peer Small Web apps, see the End-to-end encrypted peer-to-peer Small Web apps tutorial.

  If you want to install not the latest version of Kitten but the latest version for a given API version, modify your download command to tack the api version to the URL and to pass it as an argument to the bash script. For example, if you wanted to install the latest Kitten package for API version 1 using CURL, your command would look like this:

    curl -sL https://kittens.small-web.org/install/1/ | bash -s -- 1
  

  If you’re running an “immutable” Linux distribution like Fedora Silverblue, please install Kitten from your host account (instead of from within a container) at least once so Kitten can set unprivileged ports to start from 80 (so it can run without elevated privileges).

Updating Kitten

You can update Kitten in a variety of ways:

• If you use the command-line during development, run the kitten update command.

• If you want to manually update Kitten in a deployed app, you can use the web interface on the Kitten Settings page (/🐱/settings/kitten/).

• If you have a deployed app that uses Kitten Versioning, both Kitten and the installed app will be automatically updated. These updates will ensure that Kitten is not updated if the installed app itself has not been updated to support the latest Kitten API version to ensure that deployed apps do not break due to breaking changes in major API version of Kitten.

  Note that this API version guarantee will only come into effect after Kitten reaches API version 1. Kitten is currently in pre-release at API version 0.

Authoring

HTML

You work with HTML in Kitten using Kitten’s html tagged template string format that is exposed at kitten.html.

e.g., Here’s a simple page route that prints “Hello, world!”:

export default function () {
  return kitten.html`
    <h1>Hello, world!</h1>
  `
}

Kitten has a semi-forgiving HTML parser.

• XML-style closing tags are not required for regular HTML tags.

  For example, you can use <img> instead of <img />.

• For custom Kitten components, you must close your tags.

  So, for example:

  • Valid: <${MyComponent} />
  • Valid: <${MyComponent}>Slotted content</div>
  • Invalid: <${MyComponent}>

• The parser will make a best-effort to close unclosed tags.

  So, for example, it will replace <p>Hello with <p>Hello</p> but it’s not foolproof.

  You will get an unexpected close tag error if you put flow content where phrasing content is expected (e.g., a <div> inside a <p> tag, etc.)

• Comments in HTML are stripped from the final output.

  There’s currently no way to include comments in the markup generated by Kitten.

The page tag

You’ll notice in the Hello, world! example that we just returned a <h1> tag instead of the full HTML structure for the page.

Kitten has a default template that creates the boilerplate of an HTML page for you (the whole structure, starting with <!doctype html><html lang='…'><head>…, etc.)

To add to parts of this template you can use two mechanisms:

1. The <page> tag
2. Special page slots

The page tag takes the following attributes:

HTML attributes

These customise the <html> tag:

• lang (default en)

Head attributes

These customise the <head> tag:

• title: sets contents of <title> tag (default: automatically set based on first heading in page, otherwise empty)

• charset: sets contents of <meta charset='…'> tag (default: UTF-8)

• viewport: sets contents of <meta name='viewport' content='…'> tag (default: width=device-width, initial-scale=1.0)

• icon: sets contents of <link rel='icon' href='…'> (default: data:,)

Body attributes

These customise the <body> tag:

• bodyClass: sets class=… on body (default: '')

Libray includes

These attributes trigger library includes:

• htmx: includes Kitten’s internal version of htmx
• idiomorph: includes Kitten’s internal version of the htmx idiomorph extension
• ws: includes Kitten’s internal version of the htmx WebSocket extension
• alpine: includes Kitten’s internal version of Alpine.js
• css (includes the Water semantic CSS library)

Other attributes

These attributes customise other Kitten-specific behaviour:

• syntax-highlighter: turns on syntax highlighting for the page (includes the default syntax highlighting themes – see below – that are applied to any code blocks marked up in HighlightJS. Kitten’s Markdown parser automatically generates code fences with HighlighJS markup).

• syntax-highlighter-theme-light: sets the href of the lightmode Highlight.js stylesheet to use. (default: ‘/🐱/library/highlight.js/styles/measured-light.css’)

• syntax-highlighter-theme-dark: sets the href of the dark mode Highlight.js stylesheet to use (default: ‘/🐱/library/highlight.js/styles/measured-dark.css’)

Request and response helpers

Kitten has a number of request and response helpers defined to make your life easier.

Request

• is (array|string): returns true/false based on whether the content-type of the request matches the string or array of strings presented.This is used internally for Express Busboy compatibility but you might find it useful in your apps too if you’re doing low-level request handling.

Response

• withCode(code, [body]): Shorthand for setting .statusCode on response and calling response.end() with an optional body. Useful when returning custom HTTP Status Codes like the ones used in the Small Web Protocol.

• ok(): Returns 200 OK.

• created(): Returns 201 Created.

• json (data): Returns a JSON serialised response of the passed data.

• jsonFile (data): Triggers a download of the passed data in JSON format.

• file (data, fileName?, mimeType?): Sends downloadable file (default name is download and default MIME type is application/octet-stream).

• get (location), seeOther (location): 303 See Other redirect (always uses GET).

• redirect (location), temporaryRedirect (location): 307 Temporary Redirect (does not change the request method).

• permanentRedirect (location): 308 Permanent Redirect (does not change the request method)

• badRequest (body?): 400 Bad Request.

• unathenticated (body?), unauthorised (body?), unauthorized (body?): 401 Unauthorized (unauthenticated).

• forbidden (body?): 403 Forbidden (request is authenticated but lacks sufficient rights – i.e., authorisation – to access the resource).

• notFound (body?): 404 Not Found.

• error (body?), internalServerError (body?): 500 Internal Server Error.

Streaming HTML

Kitten gives you a simple-to-use event-based HTML over WebSocket implementation called Streaming HTML (because you’re streaming HTML updates to the client) that you can use to build web apps.

Kitten components

Simple components

A Kitten component is any function that returns kitten.html.

So this can be as simple as:

const SayHello = () => kitten.html`
  <h1>Hello</h1>
`

Of course, static components are not very useful, so component functions usually take a parameter object with properties (or “props”, for short):

const SayAnything = ({ thingToSay = 'Hello' } = {}) => kitten.html`
  <h1>${thingToSay}</h1>
`

console.log(kitten.html`<${SayAnything} thingToSay='Goodbye' />`

The above example, for example, will output:

<h1>Goodbye</h1>

To learn more about Kitten components, see the following tutorials:

• Components and fragments
• Slots
• Layout components
• Special page slots

kitten.Component components

While simple components are great, if you use Kitten’s Streaming HTML workflow, you may find yourself having to do a bit of manual work if you want to use simple components and wire them up to listen for events from connected pages. This will become especially true if you carry out precise updates, morphing small bits of your interface in response to events and do so in a maintainable manner by breaking up your interface into small, well-encapsulated components.

To make this easier for you, Kitten provides the Component class that you can reference in your apps from the global kitten namespace.

Icons

Kitten includes a subset of the Phosphor icon set by Helena Zhang and Tobias Fried as Kitten components.

The main difference with the original set is that some icons have been removed and some have been renamed to bring the library in line with the Small Technology Principles.

Specifically:

• All brand icons for Big Tech/Silicon Valley/surveillance capitalists/people farmers have been removed.

• The words ‘user’ and ‘users’ have been replaced with ‘person’ and ‘people’. (In Small Tech and on the Small Web we don’t have users, we have people, and we treat them as such.)

  e.g., The Phosphor icon called user-check exists as a Kitten component at kitten.icons.PersonCheck. The icon “user” has been renamed to “person-close-up” (as there is already a “person” icon) and may be found at kitten.icons.PersonCloseUp.

• The BTC icon has been removed (proof of work; environmental concerns).

Finding icons

In your Kitten app, you can access the icons as simple Kitten components at the following namespace:

kitten.icons

In that namespace, you browse the icons in three ways:

• Directly, by name, e.g., kitten.icons.Cat
• In categories, e.g., kitten.icons.categories.nature.Cat
• Using tags, e.g., kitten.icons.tags.kitten.Cat

To get autocompletion in your editor, your editor must support the TypeScript language server (any modern code editor worth using will e.g., Helix editor, etc.) and you must install and use the type-safe Kitten globals module:

import kitten from '@small-web/kitten'

kitten.icons.categories. // Will show a pop-up with list of categories in your editor.

Using icon components

You can use the components in your kitten.html as you would any other Kitten component.

e.g., A simple Kitten page that displays a large, pink cat icon in duotone:

export default function () {
  return kitten.html`
    <${kitten.icons.Cat}
      size=40%
      weight=duotone
      colour=deeppink
    />
  `
}

As the icons are Kitten components, you can customise how they appear by passing properties (“props”) to them:

• alt: Alternative text (alt-text). Provide this to explain the purpose of the icon for people who use screen readers. If no alt text is provided, it will default to the name of the icon.

• colour: Pass a CSS colour. Defaults to currentColor, which will pick up the colour of its context.

• weight: One of regular, light, thin, fill, or duotone. Defaults to regular.

• size: Pass a CSS measurement to use as the width/height (the icons are square). Defaults to 1em.

• mirror: Pass a boolean. Mirroring can be useful in right-to-left layouts. Defaults to false.

And other props you provide will be passed as attributes to the SVG tag of the icon.

Extending icon components

You can extend the SVG (e.g., to add animation, etc.) by slotting any valid SVG content into it.

e.g., This makes the cat into a Cheshire cat (fades in and out):

export default function () {
  return kitten.html`
    <${kitten.icons.Cat}
      size=40%
      weight=duotone
      colour=deeppink
    >
      <animate
        attributeName="opacity"
        values="0;1;0"
        dur="3s"
        repeatCount="indefinite"
      />
    </>
  `
}

While the above example is good for a one-time use modification, you can, of course also make a reusable CheshireCat component.

Here’s one that has all the same defaults as the one in the above example but is fully configurable via props.

const CheshireCat = ({duration = 3, minOpacity = 0, maxOpacity = 1, ...props}) => {
  return kitten.html`
    <${kitten.icons.Cat} ...${props}>
      <animate
        attributeName="opacity"
        values="${minOpacity};${maxOpacity};${minOpacity}"
        dur="${duration}s"
        repeatCount="indefinite"
      />
    </div>
  `
}

export default function () {
  return kitten.html`
    <${CheshireCat}
      size=40%
      weight=duotone
      colour=deeppink
    />
  `
}

Displaying all icons

Here’s a simple example that displays all the icons, separated alphabetically, with their component names appearing in a tooltip when you hover over them.

You can find a screenshot of it at the top of this section.

export default function () {
  return kitten.html`
    <page css>
    <markdown>
      # All icons

      These are all the icons in the ```kitten.icons``` namespace.
    </markdown>
    ${Object.entries(kitten.icons).map(([name, Icon]) => kitten.html`
      <${Icon} size=2em weight=duotone colour=deeppink>
        <title>${name}</title>
      </>
    `)}
  `
}

Markdown support

Kitten’s Markdown support comes from markdown-it.

Kitten supports a very rich set of Markdown features including:

• typographical niceties (like converting typewriter quotes “” into curly quotes “”, etc.)

• automatic anchors for headings

• adding classes, identifiers and attributes to your markdown

  e.g.,

  # Classy heading {.myClass #identifier attribute=value attribute2="spaced value"}
  

• bracketed spans

  e.g.,

  This is my [classy span]{.myClass} and I love it!
  

• syntax highlighting via highlight.js

• figure (and figure caption)

  e.g.,

  Inline images ![like](/me.png) are rendered normally, using just an `<img>` tag.
  
  ![alt text](/images-by-themselves.jpg 'Are rendered as figures (this is the figure caption)')
  

• footnotes

  e.g.,

  Inline footnotes rock.^[Inline footnote are easy to write and update.]
  

• insert

• mark

• subscript

• superscript

• table of contents creation

• task check lists

You can use Markdown in your Kitten apps in a variety of ways:

Markdown pages (.page.md files).

You can create whole pages using Markdown by placing your Markdown in page.md files. These pages are transpiled into JavaScript before being transpiled into HTML just like regular JavaScript pages (page.js) files.

Your Markdown pages can have front matter in YAML format.

Front matter

Kitten’s YAML front matter supports some special properties. Specifically:

script (literal block scalar)

You can include arbitrary JavaScript in a script block.

For example, here’s the Kitten Count example as a Markdown page with a script block:

---
script: |
  let count = 1
---
# Kitten count

${'🐱️'.repeat(count++)}

As this example shows, you can use JavaScript string interpolation inside of Markdown pages just as you would in a regular JavaScript file.

layout (string)

Specifies the layout template to use for the Markdown page.

The value for the layout property is a string that contains the relative path to the layout template (.layout.js file) you want to import and use.

Any custom properties in front matter are passed to the layout template as properties.

For example, if your layout template is called Main.layout.js and it is located in the layouts/ folder of your project and you want to include it in a page called index.page.md at the root of your project, your front matter might look like this:

---
layout: './layouts/Main.layout.js'
title: 'Feed me!'
author: 'Oskar Kalbag'
---

Woof.

And your layout template might look like this:

export default function MainLayout ({ SLOT, title, author } = {}) {
  return kitten.html`
    <header>
      <h1>Oskar’s blog</h1>
      <p>I am a dog.</p>
    </header>
    
    <main>
      <h2>${title} by ${author}</h2>
      ${SLOT}
    </main>

    <footer>
      <p>PS. Have you fed me?</p>
    </footer>
  `
}

kittenPage (true or false; default is false)

Determines whether the resulting page exports a simple page render function (when kittenPage is not provided or when it is set to false) or a Kitten.Page subclass.

Setting kittenPage: true in your front matter will enable you to use the Streaming HTML workflow with any components you attach to your page (as you will be able to author event handlers on them and, due to the Kitten Component hierarchy and automatic event bubbling, their handlers will get called).

Since your markdown pages are markdown and not JavaScript, they cannot export any event handlers of their own.

Custom properties in front matter

Any properties other than the special ones listed above are passed to your page’s layout template (if it has one) as props.

In addition to any custom properties you may have, three built-in properties are always passed to the layout template by Kitten:

• page: reference to the current page, if this is a live/connected page (KittenPage instance.)

• request: reference to the KittenRequest object. (A Node.js http.IncomingMessage object as as extended by Polka and then again by Kitten. The important Kitten addition is the session property that refers to the current session.)

• response: reference to the KittenResponse object. (A Node.js http.ServerResponse object as extended by Kitten. Kitten mixes in a number of useful response helpers.

When using JavaScript-based live pages, you can get references to the page from this.page and to the request and response objects via this.page.request and this.page.response from any connected component. However, since Markdown pages are not live pages, Kitten passes the references for you and you have no way of passing them to your layout component yourself in Markdown.

Markdown fragments

You can place static pieces of Markdown into Markdown fragment files (fragment.md).

Markdown in Kitten HTML tagged template strings

Finally, you can embed Markdown directly in your Kitten HTML tagged template string by surrounding your Markdown content between <markdown>…</markdown> tags.

e.g.,

export default () => kitten.html`
<h1>This is HTML</h1>
<markdown>
  - _This_
  - is
  - __Markdown!__
</markdown>
<footer>
  <p>This is more HTML</p>
</footer>
`

Syntax highlighting

Syntax highlighting in Markdown is provided via Highlight.js.

To turn on syntax highlighting for your page, include a <page> tag in your file that includes the syntax-highlighter attribute:

<page syntax-highlighter>

The default themes for light and dark mode are the Measured Light and Measured Dark accessible syntax highlighting colour scheme implementations for Highlight.js.

You can override this setting by setting the syntax-highlighter-theme-light and syntax-highlighter-theme-dark attributes of your <page> tag to the absolute or relative path to the respective theme CSS file.

View the full list of default Highlight.js themes.

Symlinks

If you have symlinks with extensions that Kitten knows how to route, your symlinks will get routed as if they were regular files.

e.g., You have a README.md file and you want the index of your page to display it without redundancy. Create a symlink inside your project folder:

ls -s ./README.md index.page.md

Now, when you hit the index of your site, you will see the README file.

Deploying a Kitten application

To deploy your app as a service, you use the deploy command from a regular account (not root) under Linux:

kitten deploy <httpsGitCloneURL>

For example, the following will create and run a production server of the Persisted Kitten Chat example, as hosted on my personal Codeberg account at my hostname.

kitten deploy https://codeberg.org/aral/persisted-kitten-chat

Then, as Kitten runs in an unprivileged account, you have to tell systemd to let services for that account remain running when you sign out of your server (otherwise your Kitten server will stop when you exit your ssh session or log out of your server).

e.g., If you installed Kitten under a Linux account called kitten:

loginctl enable-linger kitten

Updating a deployed Kitten application

There are a number of ways you may wish to update your deployed Kitten application, depending on who the audience for your app or site is.

• If you’re making a Small Web app that you envision being used by everyday people who use technology as an everyday thing, then you will want to implement Kitten versioning in your Git source code repositories.

  If you use Kitten versioning in your apps, Kitten periodically and automatically checks for updates to your deployed app and makes sure your deployment is up-to-date.

• If you are building something for yourself and you’re happy to manually update the site, you can do so from the App Settings page of your Kitten site (/🐱/settings/app/).

• If you’re building something for yourself and you want your Kitten site to update every time you push to the main branch of your Git repository, you can set up a webhook.

🪝Webhook

You can set up a webhook on your remote Git source code repository that updates the site whenever you perform a certain git action (e.g., push to main).

You can find your webhook URL and webhook secret on the App Settings page of your Kitten site (/🐱/settings/app/).

Your Kitten site expects the webhook secret in either the Authorization header or in the body of a POST request in a field called secret (the body should be application/x-www-form-urlencoded).

e.g., Instructions for Codeberg:

1. From your project’s repository, follow the Settings link.
2. In the Settings menu, select Webhooks.
3. Press the Add webhook button.
4. From the button’s pop-up menu, select Forgejo.
5. Enter the Webhook URL from below into the Target URL field.
6. Leave the HTTP method set to POST.
7. Set the POST content type to application/x-www-form-urlencoded.
8. Leave the Secret field empty.
9. Set Trigger on to Push events
10. Set Branch filter to main (or set to the branch you want to deploy from)
11. Enter the Webhook secret from below into the Authorization header field.
12. Leave the Active checkbox checked.
13. Press the Add webhook button.

Once the webhook has been successfully added, your site should update whenever you git push to main.

This is a feature that will be useful to developers who are deploying their own sites and apps for their own use as opposed to developers making apps for use by everyday people who use technology as an everyday thing. For the latter use case, please see Versioning, below.

Versioning

You version your Small Web apps using git tags:

Tag your Small Web apps in the following format to version them:

<Kitten API Version>.<App Version>

Where:

• Kitten API Version is the version of the Kitten API that your app is compatible with.
• App Version is the version of your app, a monotonically increasing integer that starts at 1.

To tag your app, simply use the git tag command as usual, e.g.,

git tag -s 1.3

The above tag will label your current commit as being compatible with Kitten API Version 1 and having an app version of 3.

If a deployed version of your app is running version 1.2, it will not be updated when you push commits to your main branch, etc. It will also not update the installed version of Kitten if, say, a new Kitten package is released that has an API Version of 2. Kitten will only be upgraded to the latest version when you release a version of your app that’s tagged with support for Kitten API Version 2. e.g.,

git tag -s 2.1

Automatic updates of Small Web places and of Kitten itself follows one of the core tenets of the Small Web which is that Small Web places should not require technical knowledge to maintain.

As such, updates should never a break a Small Web place and require technical intervention to fix.

This means that your Small Web apps must never break backwards compatibility. So, for example, if you have schema changes in your database, you must write migration code to give existing data the shape that the latest version of your code requires, etc.

Automatic versioning in production

To understand how automatic versioning in production works, imagine that you deploy a new server running a Kitten version that has its API version set to 1. You specify this API version in your git tag as shown above. Whenever Kitten checks for Kitten updates, it ensures that the API version is still 1 before updating Kitten.

Say that after three Kitten updates, Kitten notices that the latest version of Kitten has an API version of 2 but that your app (which Kitten is also periodically checking for updates for from its git repository) is still at API version 1. At that point, Kitten does not install the latest version of Kitten but rather waits for you to test your app with Kitten API version 2 and specify that it is supported by creating a new git tag accordingly.

If there are any other Kitten packages released that support Kitten API version 1 (e.g., bug/security fixes that are backported from the latest versions of Kitten), Kitten will continue to update itself to those versions.

Once Kitten sees that you’ve updated your app to Kitten API version 2, it will go ahead and update itself to the latest package supported by that version.

So, all this to say that Kitten tries its hardest to ensure that its auto-updates system does not break your servers.

🌲 Evergreen Web (404 → 307)

Kitten has built-in support for the Evergreen Web (404 to 307) technique.

To implement 404 to 307 redirection for your Small Web place in Kitten, simply set domain you want to forward to in your Small Web Settings page which you can reach in your browser at /🐱/settings/.

Let’s say you are deploying your new Small Web place at your own domain (e.g., https://ar.al) but you already have a personal web site or a blog there. You will already have content that other people might have linked to and/or rely on. It would be a shame for all those links to break when you deploy your new site.

The Evergreen Web (404 to 307) technique is very simple:

On your new site, issue a 307 redirect for any paths that result in a 404 (not found) error to the previous version of your site. That way, if the path existed in the previous version of your site, it will be found there and, if it did not, it will result in a 404 error there.

By using 404 to 307, you will contribute to an evergreen web by not breaking URLs.

To see it in action, run the evergreen-web example.

For more information, see 4042307.org.

Cascading archives

Similar to the Evergreen Web technique, but useful when your old site was static (or if you output a static version of your old site).

Kitten looks for three special folders:

• __archive__1
• __archive__2
• __archive__3

If they exist, it serves their contents as static files from the root of the site.

These routes are added after all other routes.

So if a route cannot be found in the current version of your site, Kitten will search for it in the above archives, in the order shown above.

Valid file types

Kitten doesn’t force you to put different types of routes into predefined folders. Instead, it uses file extensions to know how to handle different routes and other code and assets.

Here is a list of the main file types Kitten handles and how it handles them:

HTTP routes

HTTP data routes are served in response to an HTTP request for the specified method and path.

All HTTP request methods are supported.

You create an HTTP route by create a JavaScript file named with the HTTP request method you want to respond to.

For example, to respond to GET requests at /books, you would create a file named books.get.js in the root of your source folder.

The content of HTTP routes is an ESM module that exports a standard Node route request handler that takes http.IncomingMessage and http.ServerResponse arguments.

For example, your books.get.js route might look like this:

export default ({ request, response }) => {
  const books = kitten.db.books.get()
  response.end(books)
}

URL normalisation

Kitten automatically normalises URLs that do not have a trailing slash when they should to add one.

It does so using a permanent 308 redirect that preserves the method of the request.

This means, for example, that a request to _https://my.site/hello_ will be forwarded to _https://my.site/hello/_.

This is both to help implement canonical paths for your sites/apps and to avoid the unexpected situation of a relative include failing from your page if a slash is not provided in the path. (e.g., if you have an index.js file and an index.html file in a folder called hello and you include the JavaScript file using <script src='./index.js'></script>, that will succeed if the page is hit as /hello/ but fail if it is hit as /hello.)

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.

You can also manually check if the owner of the site is signed in by checking if request.session.authenticated is true or not.

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.

Data scopes

In Kitten, you have a number of different scopes, with varying lifetimes, where you can store data.

These are, from most limited and ephemeral to widest and most permanent:

Database

Kitten has an integrated JSDB database that’s available from all your routes as db.

JSDB is a transparent, in-memory, streaming write-on-update JavaScript database for the Small Web that persists to a JavaScript transaction log.

Tables in JSDB are simply JavaScript objects or arrays and JSDB writes to plain old JavaScript files.

You can also create type-safe databases. To learn how to do so, read the Database App Modules tutorial.

You can inspect and alter your database from the Kitten’s interactive shell while your app/site is running.

You can also get information about the database and specific tables, delete the whole database and specific tables, and tail specific tables using the command-line interface via the db info [tableName] (or just db [tableName], which is a convenience alias), db delete [tableName] and db tail <tableName> commands.

To access the JavaScript source code of your database, follow the “Open app data folder” link in Kitten’s initial terminal output.

Route parameters

You can include route parameters in your route paths by separating them with underscores and surrounding the parameter names in square brackets.

For example:

manage_[token]_[domain].socket.js

Will create a WebSocket endpoint at:

/manage/:token/:domain.socket

You can also intersperse path fragments with parameters:

books_[id]_pages_[page].page.js

Will compile the Kitten page and make it available for HTTP GET requests at:

/books/:id/pages/:page

So you can access the route via, say, _https://my.site/books/3/pages/10_.

You can also specify the same routes using folder structures. For example, the following directory structure will result in the same route as above:

my-site
  ╰ books
     ╰ [id]
         ╰ pages
             ╰ [page].page.js

Note that you could also have set the name of the page to index[page].page.js_. Using just [page].page.js for a parameterised index page is a shorthand.

You can decide which strategy to follow based on the structure of your app. If, for example, you could access not just the pages but the references and images of a book, it might make sense to use a folder structure:

my-site
  ╰ books
     ╰ [id]
         ├ pages
         │   ╰ [page].page.js
         ├ references
         │   ╰ [reference].page.js
         ╰ images
             ╰ [image].page.js

You may, or may not find that easier to manage than:

my-site
  ├ books_[id]_pages_[page].page.js
  ├ books_[id]_references_[reference].page.js
  ╰ books_[id]_images_[image].page.js

Kitten leaves the decision up to you.

Optional parameters

To create an optional parameter, prefix your parameter name with optional- inside the square brackets.

For example, the following route:

delete
  ╰ index_[subdomain]_[optional-return-page].page.js

Will match both of the following paths:

• /delete/my-lovely-subdomain/
• /delete/my-other-subdomain/troubleshooting/

The wildcard parameter

Finally, you can also use the special wildcard parameter to match any string:

my-site
 ╰ books_[any].page.js

The about route will match any path that begins with /books/.

App Modules

When working on larger projects, you might end up with pages at varying levels within the site, all of which need to use the same global resource (for example, a layout template or a utility class).

In these situations, your import statements might start to get unruly.

Take the following example:

my-site
  ├ site.layout.js 
  ╰ books
     ╰ the-handmaids-tail
         ╰ pages
             ╰ cover.page.js   

Let’s say your cover.page.js uses the site layout template.

Here’s what its import statement would look like:

import Site from '../../../site.layout.js'

export default () => kitten.html`
  <${Site}>
    …
  </>
`

That’s both cumbersome to write and error-prone. (Especially when you consider that different pages at different levels of the hierarchy may want to use the same file. You don’t want to spend your day counting dots.)

Enter App Modules.

App Modules are special local Node modules that exist only in your app (not on npm). They live in the special app_modules folder in your project and Kitten knows to ignore them when calculating its routes from the file structure of your project.

App Modules, like all Node modules, need a package.json file but they can get away with specifying a subset of the information contained in ones for npm packages. And, like all Node modules, they need to be npm installed into your project (but from a local file path instead of from npmjs.org).

Finally, if you have type checking enabled in your projects, you should add an index.d.ts file to your App Modules so your editor doesn’t complain when using the TypeScript Language Server (LSP).

Here’s how you’d make your site layout into an App Module:

1. Create the app_modules directory and then a directory for your module:

   mkdir -p app_modules/site-layout
   

2. Add the files your module will need:

   my-site
     ├ app_modules
     │  ╰ site-layout 
     │     ├ site.layout.js
     │     ├ index.d.ts
     │     ╰ package.json
     ╰ books
        ╰ the-handmaids-tail
            ╰ pages
                ╰ cover.page.js  
   

3. In your package.json file, you need to specify three properties: name, type, and main:

   {
     "name": "@app/site-layout",
     "type": "module",
     "main": "site.layout.js"
   }
   

4. Finally, if you have type checking enabled and you want to avoid type errors in your editor, your index.d.ts file should look like this:

   import SiteLayout from './site.layout.js'
   export default SiteLayout
   

And that’s it.

All you need to do then is to install the App Module.

From the root of your project, install your module using its local path:

npm install ./app_modules/site-layout

Finally, from cover.page.js (and any other page, anywhere in your project) you can now import your layout using:

import Site from '@app/site-layout'

That’s much better, isn’t it?

Database app modules

Database app modules are special type of app module that Kitten expects to have the name database.

You are not limited to using the default, untyped database Kitten sets up for you.

The default database, like many of the beautiful defaults in Kitten, exists to make it easy to get started with Kitten and use it to build quick Small Web places, teaching programming, etc.

If, however, you’re designing a Small Web place that you will need to maintain for a long period of time and/or that you are going to collaborate with others on, it would make sense to create your own database and to make it type safe so you get both errors and code completion during development time.

You can create your own custom database using a special type of app module called the database app module.

Like any other app module, your database app module goes in the special app_modules directory in the root of your project. What’s special is that the app module must be called database.

Static files

You do not have to do anything special to server static files with Kitten. It is, first and foremost, a web server, after all. Any file that’s in your project folder that isn’t a hidden file or in a hidden folder and isn’t a special Kitten file (e.g., .page.js, .socket.js, .post.js, etc.), will be served as a static file.

Reserved routes

Kitten tries to be as minimally invasive into your site or app’s own namespace as possible. That said, there are certain routes that it does reserve. Some of these are part of the Small Web protocol and others are Kitten-specific.

Reserved Kitten-specific routes

Kitten-specific routes are kept in the 🐱 namespace so as not to pollute your app/site’s own URI space.

These includes routes for default functionality that Kitten provides like the sign-in and sign-out routes as well as the settings interface:

• /🐱/settings (authenticated route)

• /🐱/sign-in

• /🐱/sign-out

Reserved Small Web protocol routes

The following routes are reserved as part of the Small Web protocol, which is namespaced by the Small Web emoji/logo (💕).

They are used to implement public-key authentication and manage the communication between Small Web instances and the Domain hosts that host them:

• /💕/id

• /💕/id/ssh

The Small Web protocol also defines a separate 🤖 (robot) namespace for the server itself (as opposed to the Small Web namespace which is for the person who owns and controls the Small Web place).

Currently, that only contains the following route which returns the server’s public ED25519 signing key:

• /🤖/id

(This is used during server-to-server communication to ensure that requests actually originate from the server they purport to.)

Kitten currently does not implement the full Small Web protocol. (The Small Web protocol is, itself, a work in progress.) It is currently up to apps to implement aspects of it in ways that make sense for them.

For example, Place is in the process of implementing the following routes:

• /💕/follow
• /💕/profile

In time we’ll see whether or not it makes sense to pull in more base Small Web protocol implementations into Kitten proper.

Kitten client-side libraries

Kitten comes with several client-side libraries which are automatically served at runtime that you can use in your sites/apps.

The page tag provides a high-level interface for including most of them on your pages.

For example, to include htmx, you can add the following page tag to any HTML fragment that ends up on your page:

<page htmx>

You can also include any of them in your sites/apps manually, just like any other client-side script, by knowing their paths:

In /🐱/library/:

The libraries also have minified and gzipped version (.min.gz) that are automatically used in production.

🐢 Kitten’s interactive shell (REPL)

Introduction

Kitten has an interactive shell (REPL) that extends the default Node.js REPL with Kitten-specific features.

When working with Kitten interactively (i.e., during development), you can launch the shell using the s key from any Kitten instance running in your terminal.

You’ll know you’re in Kitten’s interactive shell when you see the following prompt:

🐱 💬

If you’ve deployed Kitten as a system service (daemon) using systemd, you can use the kitten shell command to connect to the daemon over a socket connection.

Commands

In addition to executing JavaScript statements, Kitten also provides a number of useful custom commands you can use. These commands always begin with a dot.

For a full list of available commands, including ones inherited from Node.js’s own REPL, use the .help command.

.ls

The .ls command shows you the keys of Kitten’s global kitten object – one of the most useful objects you can access in Kitten’s shell.

It is a convenience function for the more verbose Object.keys(kitten) JavaScript statement that you can also use for the same purpose.

.id

Shows your Small Web place ID (ed25519 public key) if you have one.

Otherwise, prompts you to use the .id create command to create your Small Web place secret.

.id create

Creates your Small Web place secret (ed25519 private key, encoded as a lovely emoji string that you should keep in your password manager).

The output looks something like the following:

   🆔 Identity

 » New ID created.

🔑 This is your secret:

.settings

Shows the URL for accessing the Kitten Settings page of your app.

e.g., If you’re running it in development on the default port, it’ll return:

https://localhost/🐱/settings/

.sign-in

Shows the Sign In page URL for authenticating with your Kitten app.

e.g., If you’re running it in development on the default port, it’ll return:

https://localhost/💕/sign-in/

.sign-out

Shows the Sign Out page URL for signing out of your current session on your Kitten app.

e.g., If you’re running it in development on the default port, it’ll return:

https://localhost/💕/sign-out/

.stats

Shows statistics about your Kitten app (including statistics on event handlers and listeners) as well as any other Kitten processes that might be active on your machine, as well as basic statistics on all running processes and on the machine itself.

Command-line interface (CLI)

Default command

serve

kitten [path to serve] [options]
kitten serve [path to serve] [options]

Serves a Kitten place.

Options

• --domain : Main domain name to serve site at. Defaults to hostname in production, localhost during development.
• --aliases : Additional domains to respond to (each gets a TLS cert and 302 redirects to main domain). e.g., www.<hostname>
• --port : The port to create the server on. Defaults to 443. Pass --port or --port=0 for random port.
• --open : Open the page in the default browser.
• --working-directory: The working directory Kitten was launched from. Defaults to current directory (default .)

When running multiple Kitten instances to test peer-to-peer web functionality during development, remember to use a different domain and port for each instance (for example, place1.localhost for one and place2.localhost:444 for the other) to ensure that sessions work correctly.

This is because Kitten sessions make sure of cookies and cookies do not provide isolation by port.

Kitten supports four localhost subdomains (place1 to place4) that can be run on any valid port for testing peer-to-peer Small Web apps locally.

Database commands

db (alias for db info)

kitten db [table name]
kitten db info [table name]

Shows database and table information.

db delete

kitten db delete [table name]

Deletes either the whole database or the table with the specified table name after asking you for confirmation.

db tail

kitten db tail <table name>

Shows a summary of the head (start) and tail (end) of your database table (remember that database tables in JSDB are append-only JavaScript logs) and starts to follow additions to it.

Press Ctrl C to exit as you would a regular shell tail command.

Deployment of Kitten applications

deploy

kitten deploy <git HTTPS clone URL> [options]

Creates a Kitten place by deploying a Kitten project from a git repository as a systemd service.

Options

• --domain : Main domain name to serve site at. Defaults to hostname in production, localhost during development.
• --aliases : Additional domains to respond to (each gets a TLS cert and 302 redirects to main domain). e.g., www.<hostname>

run

kitten run <git HTTPS clone URL> [options]

Is the little brother of the deploy command. Runs a Kitten project from a git repository locally as a regular process.

It’s options are the same as that of the default serve command.

Kitten daemon (systemd service) commands

status

kitten status

Shows Kitten systemd service status.

logs

kitten logs [options]

Tails (follows) the Kitten systemd service logs using journald.

Options

• --since: Time span to show logs for. For example, 6 hours ago, yesterday, etc. (defaults to 1 hour ago).

start

kitten start

Starts the Kitten systemd service.

stop

kitten stop

Stops the Kitten systemd service.

enable

kitten enable

Enables the Kitten systemd service (so it auto starts on boot and if the process exits)

disable

kitten disable

Disables the Kitten systemd service (so it no longer auto starts on boot, etc.)

General commands

version (aliases: --version and -v)

kitten version
kitten --version
kitten -v

Displays the Kitten version, made up of:

• Date of the build (the Kitten’s birthday)
• The git commit hash of the build (as represented by the RGB colour equivalent of the hex value; the Kitten’s favourite colour)
• The API version (the major semver component from package.json.)

help (aliases: --help and -h)

kitten help
kitten help <command name>
kitten <command name> --help
kitten <command name> -h

Use kitten help to access command information from your terminal.

To get detailed help on a specific command, use kitten help <command name>. For example, kitten help serve.

You can also pass the --help or -h option to any command to get more detailed information about it. So kitten serve --help is equivalent to kitten help serve.

update

kitten update
kitten update <API version>

Use kitten update to update (upgrade or downgrade) your currently installed version of Kitten.

When you run the command without supplying the optional API version argument, Kitten will attempt to update to the more recent publicly-available Kitten package from kittens.small-web.org. If your version of Kitten is more recent than the most recent publicly-available Kitten package, Kitten will prompt you to ask if you want to downgrade your installation.

If you supply the optional API version argument, the update will check for the latest version for the given API version. If such an API version does not exist, you will get an error. If your version of Kitten is already on that API version but is a more recent build, you will be prompted whether you want to downgrade your installation.

uninstall

kitten uninstall

Uninstalls Kittens and removes all Kitten data after asking for confirmation.

Troubleshooting

Here are some edge cases you might encounter (because others have encountered them) and what you can do about it:

Linux: Untrusted localhost TLS certificates in Chrom(ium)

If at some point Chrom(ium) starts complaining that your development-time localhost certificates are untrusted under Linux, check that you haven’t accidentally installed a copy of ca-certificates and/or p11-kit in your unprivileged account using a third-party package manager like Homebrew (brew).

If this is the issue, you should:

1. Remove the ca-certificates and p11-kit packages from Homebrew (you will also have to remove any packages that depend on them. e.g., python, OpenSSL, etc.)
2. Restart your machine.
3. Run sudo update-ca-trust extract
4. Uninstall Kitten (kitten uninstall)
5. Reinstall Kitten via the one-line installation command or from your working copy of the source code (./install)

That should do it.

To check if your system trust store is set up correctly, you can run the following command:

trust list --filter=ca-anchors | grep Localhost

And you should see output that resembles the following:

label: Localhost Certificate Authority for aral at dev.ar.al

Building Kitten

While developing Kitten, it’s best practice to run the install script and use the kitten command to run your installed build.

./install

A typical run of the install commands takes about half a second on a modern computer so it should not impact your development velocity negatively.

./install --npm

There is a separate build command (called internally by the install script) and if you use that, you will find the distribution under the dist/ folder.

To run Kitten from the distribution folder, use the following syntax:

dist/kitten [path to serve]

Debugging

To run Kitten with the Node debugger active (equivalent of launching Node.js using node --inspect), start Kitten using:

INSPECT=true kitten

Profiling

You can see profiling information provided by Kitten’s console mixin methods profileTime() and profileTimeEnd() by passing the PROFILE=true environment variable:

e.g.,

PROFILE=true kitten examples/streamiverse

Flame Graphs

To narrow down performance issues by time spent on the stack, you can have Kitten generate a flame graph by setting the FLAME_GRAPH environment variable to true.

e.g.,

FLAME_GRAPH=true kitten examples/streamiverse

This will start your project in production mode and globally install and use the 0x node module to capture profiling information and automatically launch a browser when the process exits to show you the flame graph.

Testing

Kitten’s tests are a work-in-progress and steadily improving.

There are three types of tests in Kitten:

Unit tests

Unit tests are written in Tape With Promises, run using ESM Tape Runner, and displayed using Tap Monkey.

Coverage is provided by c8.

Run tests:

npm -s run unit-tests

Run coverage:

npm run -s coverage

Regression tests

Regression tests are written with the same stack as Kitten’s unit tests but use the Kitten and Browser test helpers to test initial output from test fixtures (the example apps).

These do not test client-side interactions, for that, please see end-to-end tests, below.

(In the future, these tests might be removed in favour of only keeping the end-to-end tests as they test similar things. The only advantage of the regression tests is that they are faster to run as they test using JSDOM instead of actual browsers.)

Run tests:

npm run -s regression-tests

End-to-end tests

End-to-end tests use Playwright, along with our custom Kitten helper for controlling the Kitten server to test Kitten’s behaviour using actual browser engines (Safari/Webkit, Firefox/Gecko, Chromium/Blink).

Run tests:

npm run -s end-to-end-tests

All tests

To perform a Kitten install and run all tests:

npm -s test

This will run unit, regression, and end-to-end tests.

Deployment (of Kitten itself)

To build and deploy a new Kitten package to kittens.small-web.org,run the deploy script:

./deploy

Core dependencies

Kitten’s renderer is built upon xhtm and vhtml although both of those libraries have been inlined and extended.

Cryptographic properties

(The functionality described in this section is currently being developed both in Domain and Kitten.)

Overview

The security (and privacy) of Domain/Kitten are based on a 32-byte cryptographically random secret string that only the person who owns/controls a domain knows.

This is basically a Base256-encoded ed25519 secret key where the Base256 alphabet is a set of curated emoji surrogate pairs without any special modifiers chosen mainly from the animals, plants, and food groups with some exceptions (to avoid common phobias or triggers, etc.) that we call KittenMoji.

🐵🐒🦍🦧🐶🐕🦮🐩🐺🦊🦝🐱🐈🦁🐯🐅
🐆🐴🧮🦄🦓🦌🦬🐮🐂🐃🐄🐷🐖🐗🐽🐏
🐑🐐🐪🐫🦙🦒🐘🦣🦏🦛🐭🐁🐀🐹🐰🐇
🎈🦫🦔🦇🐻🐨🐼🦥🦦🦨🦘🦡🐾🦃🎹🐓
🐣🐤🐥🐦🐧💕🦅🦆🦢🦉🦤🪶🦩🦚🦜🚲
🐊🐢🦎📚🐉🦕🦖🐳🐋🐬🦭🐟🐠🐡🦈🐙
🐚🐌🦋🐛🐜🐝🪲🐞🦗🎭🎁🧬🪱🦠💐🌸
🎠🌈🌹🧣🌺🌻🌼🌷🌱🪴🌲🌳🌴🌵🌾🌿
🎤🍀🍁🪺👽🍇🍈🍉🍊🍋🍌🍍🥭🍎🍏🍐
🍑🍒🍓🫐🥝🍅🫒🥥🥑🍆🥔🥕🌽🧸🫑🥒
🥬🥦🧄🧅🍄🥜🌰🍞🥐🥖💩🥨🥯🥞🧇🧀
🎶🏸🎾🎨🍔🔭🍕🌭🥪🌮🌯😸📷🌜🥚🚂
🛼🚁👾👻🥗🍿🧩🖖🥫🎸🍘🍙🍚🃏🍜🍝
🍠🍢🍣🍤🍥🥮🍡🥟🥠🩰🦀🦞🦐🦑🎡🍦
🍧🍨🍩🍪🎂🍰🧁🥧🍫🍬🍭🍮🎓🍼🎮🛹
🫖🌍🌎🌏🧭🌠🪐🪀🧵🧶🧋🎉🪁🙈🙉🙊

When setting up a Small Web app via Domain, this key is generated in the person’s browser, on their own computer, and is never communicated to either the Domain instance or the Kitten app being installed. Instead the ed25519 public key is sent to both and signed token authentication is used when the server needs to verify the owner’s identity (e.g., before allowing access to the administration area).

The expected/encouraged behaviour is for the person to store this secret in their password manager of choice.

From this key material, we derive SSH keys and the person’s server is set up to allow SSH access via this key.

Kitten running on a development machine can also recreate these SSH keys and configure the person’s SSH access to their server when the secret key is provided.

The person’s ed25519 public key is used as their identity within the system and enables their Small Web place (Kitten app) to communicate with the Domain instance for administrative reasons (e.g., to cancel hosting, etc.)

Threat model

The audience for Domain/Kitten and the Small Web in general is everyday people who use technology as an everyday thing and want privacy by default in the systems they use.

If you are an activist, etc., who might be specifically targetted by nation states, etc., please do not use this system as it does not protect against, for example, infiltration of hosting providers by nation state actors.

Given that the secret key material is generated in a web app, you must trust that the code being served by the server is what you expect it to be. Currently, there is no validation mechanism for this, although this is on the roadmap going forward (via, for example, a browser extension). This is not a problem unique to web apps, given that native apps are commonly dynamically built by app stores (at which point a nation state actor could inject malicious code) and given the lack of verifiable builds in mainstream supply chains.

You can, however, overcome this limitation by hosting Domain yourself, on your own hardware (e.g., a single-board computer like a Raspberry Pi).

The other thing to be aware of is that the security of the system is based on your secret key remaining secret and, initially at least, there will not be a way to change this secret key. (On the longer roadmap, it would be nice to provide a means of changing it but this is not a trivial process, especially if encryption keys have been derived from it and encrypted messages exist within a Kitten app).

Finally, as of September 2024 when this was last updated, the major browser engines do not yet all support ed25519/x25519 in the Web Crypto API. Specifically, while Apple (Safari) and Mozilla (Firefox) have implemented it, Google (Chrome/Chromium) hasn’t. This means that we must use a JavaScript library to handle the cryptography ad store the secret key in local storage on the client. Therefore, if a Kitten app is compromised via a Cross-Site Scripting (XSS) attack, the secret can be obtained. Once Chrome and Chromium-based browsers implement the feature by default (it is currently behind a flag), Kitten will migrate to using the Web Crypto API and the secret key will be stored in an inextractable manner that is safe from exposure via XSS.

Questions?

Contact Aral on the fediverse.