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

Trust ​

kernable assumes that any party may lie, and makes every claim checkable.

  • TLS keeps strangers off the network: over TCP, every process presents a certificate from your CA.
  • The signature proves which key sent a command, a query or a result.
  • The grant, signed by a root key, says what that key may do at all.
  • The middleware decides what the person behind the request may do, from the request context.
  • The hash chain with signed checkpoints proves afterwards that nothing stored was changed: kernable verify.

Processes and people ​

kernable authenticates processes, by their keys, not the people using your application. Who the person is, your API says in the request context (senderIdentity, senderTenant, …), signed with the API's key. The middleware decides on it: may this customer see this cart?

So two limits apply to every request, and both must allow it:

  • The key's grant limits what the process may do at all, whoever it claims to act for. A compromised API can impersonate its users, but only within its own grant: it cannot run commands it may not submit, or read events it may not listen to.
  • The middleware limits what each person may do. It builds its knowledge from events (who owns which cart, who is blocked) and fails closed while it is away.

Signing in the people themselves (passwords, sessions, tokens) happens in your API. Part 6 of the shop tutorial shows the pattern; the kit is a complete version of it as source you copy: accounts with passwords, second factors, passkeys and single sign-on, sessions, tenants, groups, and the middleware that decides on them.

Keys and grants ​

Every process has an Ed25519 key (kernable keys new). Its key ID is the public key in hex, so a signature can be checked without a registry. A signature proves who sent a message, not that the sender may do it: anyone can create a key.

So the kernel trusts root keys only (kernable start --root root.pub). A root key signs grants: a grant says what one key may do, per action and type.

sh
kernable grant root.key app.pub 'submit=shop.*' 'listen=shop.*'   # writes app.grant
ActionCovers
submitcommands the key may submit
runcommands it may run as a worker; it writes events of their domains only
subscribeevents it may read with a subscription
listenevents it may read as a listener (read model, reactor)
queryqueries it may ask
answerqueries it may answer as a read model
checkcommands and queries it may check as a middleware
privilegedprivileged request context switches it may set (bypass_authorization)
vault_readevents and commands whose vault values it gets as a listener or middleware
vault_eraseevents that erase a subject it may write as a worker
data_readdomains whose files it may read (shop.*)
data_writedomains whose files it may put and delete
cachedomains whose cache it may use
manageservices whose membership it may apply (service names, or *); with * also kernable promote
replicate*: following the kernel as its standby; the key gets every record, file and vault value
export*: exporting the whole kernel; the vault values stay sealed with its vault key
backup*: following the kernel as its backup follower; the key gets every record and file, the vault values sealed
reserved_order*: registering listeners and middlewares at negative orders, which run before every other listener; for kernable's kits (tenancy, accounts, authorization)

A type is a qualified type (shop.PlaceOrder), a whole domain (shop.*) or everything (*). A bare type ('shop.*') means every action on it.

The process sends its grant with every call, in the gRPC metadata entry kernable-grant; the SDKs read <name>.grant next to the key file. The kernel checks the chain: the grant is signed by a root key, it names the key that signed the request, and neither key is revoked. It keeps the newest grant per key. The kernel's settings hold no keys of services and no permissions, so a new service needs a grant, not a change to the kernel.

The root key is used only to issue grants and revocations, so it can stay offline. Several roots (--root repeated) allow replacing one.

A grant cannot be withdrawn. A newer grant for the same key (by its issue time) replaces it, and the kernel refuses the older one once it has seen the newer one, also after a restart: it stores the newest grant per key. Open streams follow the newer grant at once: a worker, listener or subscription whose key may no longer do what it registered for is disconnected, and one that asked for every event type gets only the types the newer grant allows from then on. Rights a key used before the newer grant stay used; to take rights away from a key that may be stolen, give the service a new key and revoke the old one.

What is signed ​

MessageSigned byProves
commandclientwho asked for exactly this, in which context
result (events, snapshot)workerwhich worker decided, based on which version
query, subscriptionclientwho asked; valid 60 s around its timestamp
stream openingworker, listenerpossession of the key (challenge)
checkpointkernelthe state of the whole log at a position
grantroot keywhat a key may do
revoke requestroot keythat a root key ended a key; valid 60 s around its timestamp
membershipa key granted managewhat a service consists of; valid 60 s around its timestamp
file and cache requestclientwho reads, writes or deletes which file or value; valid 60 s around its timestamp

Replays are harmless or refused: a command runs once per command ID, whoever sends it again; a result is bound to its command and the version it was decided on; queries, subscriptions, file and cache requests, revocations and memberships are valid only for 60 s around their timestamp, and mutual TLS keeps others from capturing them.

Acknowledgements, query answers and middleware verdicts are not signed: they travel on a stream whose key was proven, and are not stored. The exact byte layouts and test vectors are in Signatures.

The hash chain ​

Every claim is signed, every event is chained to the one before, and kernable verify checks it all.
CommandEventSignatureRejection / mismatch

Every stored event's hash covers its content, its worker's signature, its request context and the previous event's hash. The kernel signs a checkpoint of the chain regularly. kernable verify recomputes the chain and checks every signature: a changed, removed or reordered event shows, and so does a command without its client's signature. Events after the last checkpoint are protected by the chain only.

Revoking and changing keys ​

A key that leaked is revoked from the time it may have been used: a root key signs the revocation (kernable revoke) and sends it to the running kernel. The kernel stores it signed with its own key, refuses the key from then on, ends its sessions, and kernable verify lists everything the key signed since that time as suspect. A revocation is never undone. Keys change without a restart: a new key needs only its grant, a listener moves to a new key whose grant succeeds the old one, and the kernel reads its own key file again on SIGHUP. See Keys per service, and changing a key.

If something is compromised ​

CompromisedWhat an attacker can doWhat limits it, and what you do
a client's keysend what its grant allows, as that client, in the name of any person it claimsnarrow grants per service; the middleware still decides per person; revoke the key from the suspected time, and kernable verify lists everything it signed since as suspect
a worker's keyconnect as a worker for its command types and decide those commands wronglyit can only answer commands that clients signed, and write events of its own domains; revoke it, and verify flags its results
a listener's keyread the events, and vault values, its grant allowsnarrow listen and vault_read grants; revoke it
the kernel's keysign checkpointsstored events still carry the client's and worker's signatures, which it cannot forge; replace the key file and reload it (SIGHUP), and verify with every kernel key you had
a root keyissue any grantkeep root keys offline; with several roots (--root repeated), revoke the compromised one and its grants lose their effect
the store filechange, remove or reorder eventskernable verify shows every such change up to the last signed checkpoint; only events after it could be cut off unnoticed, so keep the checkpoint interval short
the vault key, with the vault fileread personal and secret valueskeep both apart from the store and its backups; kernable vault rekey re-encrypts with a new key
the UI's addressread events, payloads and connectionsit listens on loopback only, has no login, and never decrypts the vault; reach it through an SSH tunnel

Transport ​

Over TCP, the kernel requires mutual TLS: every process presents a certificate from your CA. Signatures make a message trustworthy; TLS keeps it private and keeps strangers out.

Privileged switches ​

The request context is business data and the client decides it, except for privileged switches such as bypass_authorization, which only keys granted privileged for that switch may set. Even then, the middleware decides what a bypass means; the kernel does not skip the chain.