Previewkernable is not released yet: these docs describe work in progress, and things may change before 1.0.Not released yet.Request early access →
Skip to content

Getting started with the kit ​

This page takes you from an empty directory to people signing in to your API: copy the kit, run its domains next to yours, grant its keys, send its mail, and turn a signed-in person into the request context of your own commands. The kit explains what each domain holds.

1. Copy it ​

sh
npx @kernable/sdk add kit           # into ./kit; or: add kit <dir>
npm install @node-rs/argon2 @simplewebauthn/server openid-client
node --test kit/test/unit/*.test.ts
sh
kernable-sdk add kit                # into ./kit, a package; or: add kit <dir>
pip install -r kit/requirements.txt
python -m unittest discover -s kit/tests -t .
sh
cargo install kernable-sdk
kernable-sdk add kit                # the crate ./kit; or: add kit <dir>
cargo test -p kit                   # after adding it to your workspace

The kit comes with the SDK, so its version matches your SDK's. The tests are the kit's contract: the cases every language's kit passes, as JSON in kit/fixtures. They pass in the kit as shipped; when you change a rule, change its case too.

2. Run it ​

The kit is a set of domains. Declare the relations your permissions use, then run the kit's domains next to yours:

ts
import { Kernable } from "@kernable/sdk";
import { kitDomains, relation, useAuthorizationStore } from "./kit/src/kit.ts";
import { shopDomain } from "./shop/domain.ts";

// Who stands in which relation to your aggregates, from your events.
relation("shop.order", "owner").set("shop.OrderPlaced", (e) => e.data.customer);

useAuthorizationStore("sqlite:authorization.db"); // the middleware resumes after a restart
const app = new Kernable().app({ service: "kit", domains: [...kitDomains(), shopDomain] });
await app.run();
python
from kernable import Kernable
from kit import kit_domains, relation, use_authorization_store
from shop.domain import shop_domain

# Who stands in which relation to your aggregates, from your events.
relation("shop.order", "owner").set("shop.OrderPlaced", lambda e: e.data["customer"])

use_authorization_store("sqlite:authorization.db")  # the middleware resumes after a restart
Kernable().app(service="kit", domains=[*kit_domains(), shop_domain]).run()
rust
use kernable::{App, Kernable};
use kit::authorization::{ids, relation, use_authorization_store};

// Who stands in which relation to your aggregates, from your events.
relation("shop.order", "owner").set("shop.OrderPlaced", |e| ids(&e.data["customer"]));

use_authorization_store("sqlite:authorization.db"); // the middleware resumes after a restart
let mut app = App::new().service("kit");
for d in kit::kit_domains().iter().chain([&shop_domain]) {
    app = app.domain(d);
}
Kernable::new("kit.key")?.app(app)?.run().await?;

Once, bootstrap() creates the platform tenant (where accounts and the platform's administrators live), the sign-up policy, the identity and key your API uses for itself, and optionally the first administrator. It may run again; it skips what exists.

3. Send its mail ​

Registration, password resets, email changes and invitations send mail from the kit's reactors. Until you set a mailer they print to the console, which is enough to try the kit. In production, pass an object with a send(mail) method that hands the mail to your provider:

ts
import { useMailer } from "./kit/src/shared/mail.ts";

useMailer({ async send(mail) { await smtp.send({ to: mail.to, subject: mail.subject, text: mail.text }); } });
python
from kit.shared.mail import use_mailer

class Smtp:
    def send(self, mail):
        smtp.send(to=mail.to, subject=mail.subject, text=mail.text)

use_mailer(Smtp())
rust
use kit::shared::mail::{use_mailer, Mail, Mailer};

struct Smtp;
impl Mailer for Smtp {
    fn send(&self, mail: Mail) { /* hand mail.to, mail.subject, mail.text to your provider */ }
}
use_mailer(std::sync::Arc::new(Smtp));

The texts are in the reactors files of account and invitation. When send throws, the reactor gets the event again, backing off; after 5 attempts it parks the event, and kernable listeners retry sends it once your provider is back (see Failures and recovery). A sent invitation is recorded as InvitationMailSent.

4. Grant the keys ​

ProcessGrant
the kit's servicerun on tenancy.*, account.*, identity.*, group.*, invitation.*; listen, answer and check on *; vault_read and vault_erase; reserved_order=* (its listeners run before yours); privileged=bypass_authorization (its own follow-up commands); process=* (it sets as whom each process acts)
your APIsubmit and query on what it sends; cache on account (passkey challenges and OIDC state live there for a few minutes)

See Keys per service for issuing them.

5. Sign people in, in your API ​

Your API is the one process that sees passwords, tokens and provider answers. KitApi holds what only it can do; wire it into your HTTP framework (kit/example/server.ts shows node:http, kit/example/server.py shows http.server, kit/examples/server.rs axum):

ts
const api = new KitApi({ kernable, keys: signingKeysFrom("token-signing.pem"), service });

const signedIn = await api.signIn({ email, password, ip });          // access and refresh token
const claims = api.check(accessToken);                               // per request, without the kernel
const context = await api.contextFor(claims, tenantId);              // senderAccount, senderSession, senderTenant, senderIdentity
await kernable.submit(PlaceOrder.new({ … }), { aggregateId, tenant: tenantId, context });
python
api = KitApi(kernable, signing_keys_from("token-signing.pem"), service)

signed_in = api.sign_in(email, password, ip=ip)                      # access and refresh token
claims = api.check(access_token)                                     # per request, without the kernel
context = api.context_for(claims, tenant_id)                         # sender_account, sender_session, sender_tenant, sender_identity
kernable.submit(PlaceOrder(...), aggregate_id=aggregate_id, tenant=tenant_id, context=context)
rust
let api = KitApi::new(kernable.clone(), signing_keys_from("token-signing.pem")?, &service_identity, &service_key_id);

let signed_in = api.sign_in(&email, &password, ip, None).await?;      // access and refresh token
let claims = api.check(&access_token);                               // per request, without the kernel
let context = api.context_for(&claims, Some(&tenant_id)).await?;     // sender_account, sender_session, sender_tenant, sender_identity
kernable.submit(Submit::command(PlaceOrder { .. }, &aggregate_id).tenant(&tenant_id).context(context)).await?;

In Python, KitApi blocks like the SDK's client; for FastAPI or another asyncio framework, AsyncKitApi(KitApi(...)) has the same methods, awaited. In Rust, KitApi is async.

Access tokens live 15 minutes and are checked by your API alone; the middleware still refuses an ended session, a suspended account or a revoked API key at once. Refresh tokens rotate, and using one twice ends its session. KitApi also verifies emails, resets passwords, sets up TOTP and passkeys, runs OAuth/OIDC (oidcStart, oidcFinish), checks API keys and accepts invitations.

6. Decide with groups and relations ​

A tenant's owners may do everything in it. Everyone else gets permissions through groups, for the whole tenant or one aggregate:

ts
CreateGroup.new({ name: "Customers", permissions: [
  { pattern: "shop.PlaceOrder" },
  { pattern: "shop.CancelOrder", when: "owner" },   // only orders they placed
] });
python
CreateGroup(name="Customers", permissions=[
    {"pattern": "shop.PlaceOrder"},
    {"pattern": "shop.CancelOrder", "when": "owner"},  # only orders they placed
])
rust
CreateGroup { name: "Customers".into(), description: None, permissions: vec![
    Permission { pattern: "shop.PlaceOrder".into(), ..Permission::default() },
    Permission { pattern: "shop.CancelOrder".into(), when: Some("owner".into()), via_parent: None }, // only orders they placed
] };

Nobody grants a group with permissions they do not hold. Explain answers why a request is allowed or refused, with the middleware's own steps. For lists, visibility(readModel) gives an app read model the same decision, so a list shows only what each asker may get.

Next ​

Changing the kit ​

Each domain has the same files: domain, events, aggregates, commands, readmodels, queries, reactors where it has any, and index.ts, __init__.py or mod.rs, which registers the parts. Events, commands and queries are classes, so a changed field shows wherever it is used. Settings you are likely to change (lockout, token lifetimes, reserved slugs, the passkey relying party) are in shared/constants. Fields are camelCase in TypeScript and snake_case in Python and Rust; the log holds camelCase either way.

A newer kit is not installed over yours: copy it into another directory and take over what you want.