Companies and roles

The platform admin, owners, admins and members; departments and teams; joining with a single-use link; and the three ways to sign in.

One server holds many companies. Each is a tenant of its own: its members, its groups, its records, its keys and its trail. Another company's admin who asks for something in yours is answered exactly as if it did not exist.

Status. Release 0.0.1, the first.

Who is who

Standing	What it may do
platform admin	creates companies and names each one's owner, suspends and resumes a company; is not a member of any company and opens none of its records
owner	everything an admin may do, and makes or unmakes owners; keeps the company's recovery key and hands a member's keys back
admin	adds, changes, suspends and removes members, issues their join links, makes and keys departments and teams, defines record types, reads the trail, vouches for keys, deletes any record of the company
member	keeps records, shares them, reads what is shared with them, keeps their own key set

Only an owner makes or unmakes an owner, and a company always keeps one active owner: the last one cannot be demoted, suspended or removed. A suspended member is stopped at their next request.

Joining

An owner or admin adds a person with an email, a name and a role. The server answers with the person's account id, and an enrolment token is issued for them on request; you send it to them. The token is single use and lasts 24 hours. The person opens #/join, pastes it, and sets a sign-in password and an authenticator. The platform admin's own first token comes from tessaridb-vault enrolment-link (see Running it).

Signing in

A password and an authenticator code (TOTP). The password is hashed with Argon2id under a pepper derived from the service key. Attempts are backed off per address, per address-and-password pair and per network address, and the account is never locked.
An OpenID Connect issuer, when TESSARIDB_VAULT_OIDC_ISSUER, _CLIENT_ID and _REDIRECT are set. The flow uses PKCE and checks state, nonce, iss and the ID token. A signed-in member links their identity at the issuer first, and a return completes only for the browser or the account that began it.
A passkey (Web Authentication Level 3, user verification required), which a signed-in member registers on the account page. It signs in without naming an account first. Passkeys need TESSARIDB_VAULT_PUBLIC_URL; plain http is accepted only for localhost.

Signing in is not unlocking. After signing in, each company asks for its unlock password, which the browser alone uses; see Keys and layers.

Departments and teams

A group is a department or a team, and a team may sit inside a department. A record shared with a department reaches the department's members and the members of its teams. Each group has a key pair: an admin's browser wraps the group's private key to every member inside its reach, each member reads back only their own wrap, and the members still waiting for one are listed to admins.

Taking a member out of a team or department stops them at their next request, takes their wrap off the group's key, and marks that key, its department's and every record shared through them for rotation. An admin's browser then keys the group again.

The trail

Every admin change is recorded with who, what, to whom, when and why, in the same transaction as the change, so a change whose record cannot be written does not happen. Every create, read and revision of a record is on the trail before anything is opened. A chain over each company's events shows where a row was altered: the trail page checks it end to end, and so does GET /api/companies/{company}/audit/verify.