Appearance
Accounts and sessions
An account is a person who can sign in: one email address, one password (or none), their second factors and linked logins. It is the same account in every tenant; what the person may do in a tenant comes from their identity there. Every account lives in the platform tenant.
The account domain has three aggregates:
| Aggregate | One per | Lives under |
|---|---|---|
account.account | person | the platform tenant |
account.session | sign-in; ends on sign-out, expiry or revocation | the platform tenant |
account.sso | single sign-on configuration of a tenant | that tenant |
Most of the commands here are sent by your API through KitApi, which picks session IDs, generates tokens and checks provider answers. The page explains what happens underneath.
Registration and email verification
- An account starts
pendingand becomesactivewithVerifyEmail. The token is valid forVERIFICATION_HOURS(48) and is erased once used. - Registration does not reveal who has an account. If the address is taken,
registeranswers exactly as on success. The owner of the address gets a "you already have an account" mail instead (RegistrationAttempted). - A registration that expired unverified does not block the address: registering again takes it over with a new token.
- Whether anyone may register is the platform's sign-up policy. With
accounts: off, accounts come only from invitations; an invitation proves the email, so such an account is active at once.
Signing in
SignIn checks the password against its argon2id hash and writes either SignedIn or SignInFailed with a reason: wrong_password, locked, not_verified or not_active. A missing account answers wrong_password too.
Lockout: after LOCKOUT_AFTER (5) failures in a row, the account is locked for 1 minute, then 2, 4 and so on, at most LOCKOUT_MAX_MINUTES (15). The lock is computed from the failures, not stored, and a successful sign-in resets it. Failed second factors count as well.
After SignedIn, a reactor opens the session (OpenSession). Your API then holds two tokens:
| Token | Lifetime | Checked by |
|---|---|---|
| access token (EdDSA, claims: account, session, factors) | ACCESS_TOKEN_MINUTES (15) | your API alone, per request, without the kernel |
refresh token <sessionId>.<generation>.<secret> | as long as the session | the kernel (RefreshSession) |
Refresh tokens rotate. Each RefreshSession issues the next generation. A token from an older generation is a reuse, a sign that it was stolen, so the session ends at once (reuse). Sessions also end after SESSION_IDLE_DAYS (14) without a refresh, and after SESSION_MAX_DAYS (90) in any case.
A short-lived access token does not leave a gap: the middleware learns from the events when a session ends, an account is suspended or a password changes, and refuses that session's requests at once.
Second factors
| Factor | How it is set up | Counts as |
|---|---|---|
| TOTP (an authenticator app) | StartTotp with a secret your API generated, then ConfirmTotp with the first code; it also creates 10 recovery codes, shown once | the second factor |
| recovery code | from ConfirmTotp or RegenerateRecoveryCodes; each works once | the second factor |
| passkey (WebAuthn) | AddPasskey with the browser's attestation | two factors: it proves possession and the user |
An account with TOTP on needs it in every session: until ProveSecondFactor (or ProvePasskey) succeeds, the middleware allows nothing but signing out. A tenant may require a second factor from everyone in it.
Passkeys can also be the only sign-in method: SignInWithPasskey needs no password. Passkeys are bound to your site: set the relying party with usePasskeys({ rpId, rpName, origins }).
Other ways to sign in
- Social logins (Google, GitHub, any OpenID Connect provider): configured in
KitApi. A login that is linked to an account signs in to it. A login whose email nobody has registers a new person. A login whose email belongs to an account that has not linked it is refused (not_linked): the person signs in another way and links it (LinkProvider), so nobody takes over an account through a provider. - Single sign-on per tenant (
account.sso): a tenant's owners configure their identity provider (CreateSso) and add their email domains. A domain counts once its DNS carries the TXT record_kernable-sso.<domain>(VerifySsoDomain, run by your API); each domain belongs to one tenant only. People with an address in a verified domain then sign in through that provider, and their first SSO login is linked to the account with the same email. - Enforced SSO (
EnforceSso): in that tenant, only sessions signed in through its SSO count. Owners are exempt, so a broken SSO configuration can be mended. The same person may still sign in with a password for other tenants.
Changing an account
| Change | Command | What else happens |
|---|---|---|
| password | ChangePassword (with the current one, if there is one) | every other session of the account ends; this one stays |
| forgotten password | RequestPasswordReset, then ResetPassword with the mailed token (valid RESET_MINUTES, 60) | every session ends |
RequestEmailChange, then ConfirmEmailChange with the token mailed to the new address | the old address stays until it is confirmed |
Who may do these: the account itself, or the platform. A person may suspend their own account (owner_requested); suspending for other reasons, reactivating and deleting are the platform's.
Deleting an account (DeleteAccount, from suspended) erases its personal data from every event of the account and its sessions, and deletes its identities in every tenant. An identity that still owns a tenant stops this: its deletion parks for an operator until another owner is found.
Settings
| Constant | Default | What it does |
|---|---|---|
LOCKOUT_AFTER, LOCKOUT_MAX_MINUTES | 5, 15 | failures before the lock, and its longest duration |
VERIFICATION_HOURS | 48 | how long an email verification token is valid |
RESET_MINUTES | 60 | how long a password reset token is valid |
ACCESS_TOKEN_MINUTES | 15 | the access token's lifetime |
SESSION_IDLE_DAYS, SESSION_MAX_DAYS | 14, 90 | when a session ends without a refresh, and at the latest |
PASSKEYS | localhost | the relying party; set it with usePasskeys |
CHALLENGE_SECONDS | 300 | how long a passkey challenge is valid |
The password hash parameters (argon2id, 19 MiB, 2 iterations, OWASP's recommendation) are in shared/secrets.
Reference
Types
The types the tables below name, from account/domain.ts:
ts
type AccountStatus = "none" | "pending" | "active" | "suspended" | "deleted";
type AccountSuspensionReason = "owner_requested" | "abuse" | "by_platform";
type TokenPurpose = "verify" | "reset" | "email_change";
type SessionEnd = "signed_out" | "revoked" | "account_suspended" | "password_changed" | "account_deleted" | "reuse" | "idle" | "expired";Aggregates
| Aggregate | Unique keys | Facts |
|---|---|---|
account.account | link, email | active, mfa |
account.session | — | — |
account.sso | domain (global) | — |
Commands
Secret fields leave the vault once the command completes; personal fields stay in the vault until their subject is erased.
| Command | Fields | Writes | Who may send it | Refused with |
|---|---|---|---|---|
AddSessionFactoron session | factor: stringaccountId: string | SessionFactorAdded | only the kit's reactors | invalid_session, invalid_state |
EndSessionon session | reason?: SessionEnd | SessionEnded | a group permission, or the sender itself | invalid_state |
OpenSessionon session | accountId: stringmethod: stringfactors: string[]refreshTokenHash: stringip: string | null (secret)userAgent: string | null (secret)at: number | SessionOpened | only the kit's reactors | exists |
RefreshSessionon session | refreshToken: string (secret)newRefreshToken: string (secret)ip?: string (secret) | SessionEnded, SessionRefreshed | anyone (the request carries its proof) | invalid_token |
RegisterAccounton account | email: string (personal)name: string (personal)password?: string (secret)verified?: boolean | AccountRegistered, VerificationRequested | anyone (the request carries its proof) (verified only from the API) | exists, invalid_email, invalid_name, weak_password |
RequestVerificationon account | — | VerificationRequested | the API (its api group) | invalid_state |
SignInon account | sessionId: stringpassword: string (secret)refreshToken: string (secret)ip?: string (secret)userAgent?: string (secret) | SignInFailed, SignedIn | anyone (the request carries its proof) | invalid_token, not_found |
VerifyEmailon account | token: string (secret) | EmailVerified | anyone (the request carries its proof) | expired_token, invalid_token |
SuspendAccounton account | reason: AccountSuspensionReason | AccountSuspended | the platform (the person too, with owner_requested) | invalid_reason, invalid_state |
ReactivateAccounton account | — | AccountReactivated | the platform | invalid_state |
DeleteAccounton account | — | AccountDeleted | the platform | invalid_state |
ChangePasswordon account | current?: string (secret)new: string (secret)keepSessionId?: string | PasswordChanged | a group permission, or the sender itself | invalid_state, weak_password, wrong_password |
RequestPasswordReseton account | — | PasswordResetRequested | the API (its api group) | invalid_state |
ResetPasswordon account | token: string (secret)new: string (secret) | PasswordReset | anyone (the request carries its proof) | expired_token, invalid_token, weak_password |
RequestEmailChangeon account | email: string (personal) | EmailChangeRequested | a group permission, or the sender itself | invalid_email, invalid_state, unchanged |
ConfirmEmailChangeon account | token: string (secret) | EmailChanged | anyone (the request carries its proof) | expired_token, invalid_token |
NoteRegistrationAttempton account | — | RegistrationAttempted | the API (its api group) | invalid_state |
StartTotpon account | secret: string (personal) | TotpStarted | a group permission, or the sender itself | exists, invalid_secret, invalid_state |
ConfirmTotpon account | code: string (secret)recoveryCodes: string[] (secret) | TotpConfirmed, RecoveryCodesGenerated | a group permission, or the sender itself | invalid_recovery_codes, invalid_state, wrong_code |
DisableTotpon account | code: string (secret) | TotpDisabled | a group permission, or the sender itself | wrong_code |
RegenerateRecoveryCodeson account | code: string (secret)recoveryCodes: string[] (secret) | RecoveryCodesGenerated | a group permission, or the sender itself | invalid_recovery_codes, wrong_code |
ProveSecondFactoron account | sessionId: stringcode: string (secret) | SecondFactorFailed, SecondFactorProved | anyone (the request carries its proof) | invalid_state |
AddPasskeyon account | challenge: stringresponse: RegistrationResponseJSONlabel?: string (personal) | PasskeyAdded | a group permission, or the sender itself | exists, invalid_passkey, invalid_state |
RemovePasskeyon account | credentialId: string | PasskeyRemoved | a group permission, or the sender itself | last_method, not_found |
SignInWithPasskeyon account | sessionId: stringchallenge: stringresponse: AuthenticationResponseJSONrefreshToken: string (secret)ip?: string (secret)userAgent?: string (secret) | SignInFailed, PasskeyUsed, SignedIn | the API (its api group) | invalid_token, not_found |
ProvePasskeyon account | sessionId: stringchallenge: stringresponse: AuthenticationResponseJSON | SecondFactorFailed, PasskeyUsed, SecondFactorProved | the API (its api group) | invalid_state |
SignInWithProvideron account | sessionId: stringprovider: stringsubject: string (secret)email?: string (secret)emailVerified?: booleanautoLink?: booleanrefreshToken: string (secret)ip?: string (secret)userAgent?: string (secret) | SignInFailed, SignedIn, ProviderLinked | the API (its api group) | invalid_provider, invalid_subject, invalid_token, not_found |
LinkProvideron account | provider: stringsubject: string (secret)email?: string (secret) | ProviderLinked | the API (its api group) | exists, invalid_provider, invalid_state, invalid_subject |
UnlinkProvideron account | provider: stringsubject: string (secret) | ProviderUnlinked | a group permission, or the sender itself | last_method, not_found |
CreateSsoon sso | issuer: stringclientId: stringclientSecret: string (secret) | SsoCreated | owners | exists, invalid_client, invalid_issuer |
UpdateSsoon sso | issuer: stringclientId: stringclientSecret: string (secret) | SsoUpdated | owners | invalid_issuer, not_found |
AddSsoDomainon sso | domain: string | SsoDomainAdded | owners | exists, invalid_domain, not_found |
VerifySsoDomainon sso | domain: stringfound: string[] | SsoDomainVerified | the API (its api group) | not_found, not_verified |
RemoveSsoDomainon sso | domain: string | SsoDomainRemoved | owners | not_found |
EnforceSsoon sso | enforced: boolean | SsoEnforcementChanged | owners | invalid_state |
DisableSsoon sso | — | SsoEnforcementChanged, SsoDisabled | owners | invalid_state |
EnableSsoon sso | — | SsoEnabled | owners | invalid_state |
DeleteSsoon sso | — | SsoDeleted | owners | not_found |
Events
| Event | Fields | Vault | Note |
|---|---|---|---|
AccountRegistered | email: stringname: stringpasswordHash: string | nullverified: booleanat: number | email, name, passwordHash under the aggregate | — |
VerificationRequested | tokenId: stringtoken: string | nullemail: string | nullexpiresAt: number | email under the aggregate; token under token:<tokenId> | The token stays in the vault under its own subject until it is used. |
EmailVerified | tokenId: string | erases token:<tokenId> | Erases the used token. |
SignedIn | sessionId: stringmethod: stringfactors: string[]refreshTokenHash: stringip: string | nulluserAgent: string | nullmfa: booleanat: number | ip, userAgent under the aggregate | — |
SignInFailed | method: stringreason: "wrong_password" | "locked" | "not_verified" | "not_active" | "not_linked"ip: string | nullat: number | ip under the aggregate | An event, not a rejection: audited, and it counts toward the lockout. |
SessionOpened | accountId: stringmethod: stringfactors: string[]refreshTokenHash: stringip: string | nulluserAgent: string | nullat: number | ip, userAgent under the accountId | — |
SessionRefreshed | generation: numberrefreshTokenHash: stringip: string | nullaccountId: stringfactors: string[]at: number | ip under the accountId | — |
SessionFactorAdded | factor: string | — | — |
SessionEnded | reason: SessionEnd | — | — |
AccountSuspended | reason: AccountSuspensionReasonat: number | — | Ends every session (a reactor); sign-in is refused. |
AccountReactivated | — | — | — |
AccountDeleted | — | erases the aggregate | Erases the account's personal data, in its events and its sessions'. |
PasswordChanged | hash: stringkeepSessionId: string | nullat: number | hash under the aggregate | Ends the account's other sessions (a reactor); keepSessionId is the one it was changed from. |
PasswordResetRequested | tokenId: stringtoken: string | nullemail: string | nullexpiresAt: number | email under the aggregate; token under token:<tokenId> | The reset token sits in the vault under its own subject until used. |
PasswordReset | tokenId: stringhash: stringat: number | hash under the aggregate; erases token:<tokenId> | Erases the used token; ends every session (a reactor). |
EmailChangeRequested | tokenId: stringtoken: string | nullemail: string | nullexpiresAt: number | email under the aggregate; token under token:<tokenId> | The new address gets a token; it holds nothing until confirmed. |
EmailChanged | tokenId: stringemail: string | email under the aggregate; erases token:<tokenId> | Erases the used token; the account now holds the new address. |
RegistrationAttempted | email: string | nullat: number | email under the aggregate | Someone registered with this account's address: it gets a mail saying it exists. |
TotpStarted | secret: string | null | secret under the aggregate | The TOTP secret the API generated and showed: personal, in the vault. Not in use until confirmed. |
TotpConfirmed | step: numberat: number | — | TOTP is the account's second factor from now on (the first code's step: no code twice). |
TotpDisabled | — | — | — |
RecoveryCodesGenerated | hashes: string[] | — | The recovery codes' hashes; the codes were shown once. |
SecondFactorProved | sessionId: stringmethod: "totp" | "recovery" | "passkey"step: number | nullrecoveryCodeHash: string | null | — | A session proved a second factor; a reactor adds it to the session. |
SecondFactorFailed | sessionId: stringat: number | — | Counts toward the lockout, like a wrong password. |
PasskeyAdded | credentialId: string | nullpublicKey: stringcounter: numberlabel: string | nullat: number | credentialId, label under the aggregate | A passkey: its credential ID and label are personal; the public key (COSE, base64url) is not. |
PasskeyRemoved | credentialId: string | null | credentialId under the aggregate | — |
PasskeyUsed | credentialId: string | nullcounter: number | credentialId under the aggregate | A passkey signed: its counter moves on (a cloned authenticator would fall behind). |
ProviderLinked | provider: stringsubject: string | nullemail: string | nullat: number | subject, email under the aggregate | An external login (OAuth/OIDC, or a tenant's SSO as sso:<id>) linked to the account. |
ProviderUnlinked | provider: stringsubject: string | null | subject under the aggregate | — |
SsoCreated | issuer: stringclientId: stringclientSecret: string | null | clientSecret under sso:<id> | The client secret is personal data of the configuration (sso:<id>), erased with it. |
SsoUpdated | issuer: stringclientId: stringclientSecret: string | null | clientSecret under sso:<id> | — |
SsoDomainAdded | domain: stringtxt: string | — | txt: the value the domain's DNS must carry at _kernable-sso.<domain>. |
SsoDomainVerified | domain: string | — | — |
SsoDomainRemoved | domain: string | — | — |
SsoEnforcementChanged | enforced: boolean | — | Enforced: in this tenant, only sessions signed in through this SSO count (owners excepted). |
SsoDisabled | — | — | — |
SsoEnabled | — | — | — |
SsoDeleted | — | erases sso:<id> | — |
Queries
A query about one aggregate names it (static target): the middleware decides on that aggregate as on a command's.
| Query | Fields | About | Answer | Who may ask |
|---|---|---|---|---|
FindAccountByEmailby account.accounts | email: string | — | { id: string; status: AccountStatus } | the API (its api group) |
GetAccountby account.accounts | accountId: string | account.account in accountId | AccountRow { id, email, name, status } | the API (its api group), or the sender itself |
ListSessionsby account.accounts | accountId: string | account.account in accountId | SessionRow[] | a group permission, or the sender itself |
FindAccountByLinkby account.accounts | provider: stringsubject: string | — | { id: string; status: AccountStatus } | the API (its api group) |
FindSsoByDomainby account.ssos | domain: string | — | { tenant: string; ssoId: string; issuer: string; clientId: string; enforced: boolean } | the API (its api group) |
GetSsoSecretby account.ssos | ssoId: string | — | { issuer: string; clientId: string; clientSecret: string | null } | the API (its api group) |
GetSsoby account.ssos | ssoId: string | — | Omit<SsoRow, "clientSecret"> | owners |
Listeners
| Listener | On | Submits |
|---|---|---|
account.accounts (read model, order -20) | AccountRegistered, EmailVerified, EmailChanged, ProviderLinked, ProviderUnlinked, AccountSuspended, AccountReactivated, AccountDeleted, SessionOpened, SessionRefreshed, SessionEnded | — |
account.ssos (read model, order -20) | SsoCreated, SsoUpdated, SsoDomainAdded, SsoDomainVerified, SsoDomainRemoved, SsoEnforcementChanged, SsoDisabled, SsoEnabled, SsoDeleted, TenantDeleted | — |
account.mail (reactor, order -10) | VerificationRequested | side effects only |
account.mail (reactor, order -10) | PasswordResetRequested | side effects only |
account.mail (reactor, order -10) | EmailChangeRequested | side effects only |
account.mail (reactor, order -10) | RegistrationAttempted | side effects only |
account.sessions (reactor, order -10) | SecondFactorProved | AddSessionFactor |
account.sessions (reactor, order -10) | SignedIn | OpenSession |
account.ending (reactor, order -10) | AccountSuspended | side effects only |
account.ending (reactor, order -10) | AccountDeleted | side effects only |
account.ending (reactor, order -10) | PasswordChanged | side effects only |
account.ending (reactor, order -10) | PasswordReset | side effects only |
