Organizations, teams & access
Every app instance is in exactly one organization: one its creator is in, or one made with it, as its package’s manifest says (Where an instance goes). An organization holds members with roles, nested teams (an app team per package it uses, with restricted child teams below for private channels) and the app instances, each with a list of grants that names who reaches it.
Access has two layers. The node decides who reaches an app at all, from the
app’s grants and the system state, on every request. Everything finer —
who may edit which record — is the app’s own code, which can read the caller’s
standing with env::org(), env::org_role(account) and env::in_team(account, team) (Who a run acts as).
Every rule on this page is enforced by the system group’s state machine when the command applies (The system group); the API checks most of them first so a refused request records nothing.
App access
Section titled “App access”An app instance’s access is a list of grants (types::Grant, kept as
types::Access), set at creation (POST /apps { grants }; absent: [org]) and replaced with
POST /apps/{app}/access { grants } by its owner, an organization admin, or
whoever manages its teams’ apps (MANAGE_APPLICATION on each team it admits,
which a team’s leads hold, before and after the change); a list with no team
needs MANAGE_APPLICATION organization-wide. Each grant is one way in, judged
on its own, so an instance can be “team X plus two partners from outside”:
| Grant | Who it admits |
|---|---|
org |
Every member of the app’s organization; a guest of the organization only while it has no app team. Not beside a team grant, which it covers |
team { team } |
The team’s members (direct rows, and inheritance into an open team); at most 16 teams |
account { account, scope? } |
One person. A member of the organization is a named member; anyone else is a guest, admitted only where the instance’s release and its organization allow guests. For an instance of a package with an app team in its organization, a named member must also be in that app team. scope is the app’s own (below); at most 1 000 accounts |
anyone |
Any signed-in account, a member of the organization or not. Never a caller without an account (401): anonymous visitors come in only through public links |
No grant is the owner alone. The owner reaches their app too, except that an
instance whose only member grants are teams is reached by its owner only while
they are in one of them (or named). A list with a grant twice, an unknown team or
account, org beside a team, or a scope over 256 bytes is refused where it
applies. Grants are written from cluster version 1.0.0-rc.33
(Feature::AccessGrants; 409 FEATURE_NOT_ACTIVE before). GET /apps/{app}
answers them as grants.
Whatever changes an instance’s grants keeps the rest: giving an org instance
an app team (ScopeApps) replaces its org grant with the app team’s,
deleting a team takes the instances it alone admitted
and the team’s grant from the others (or keeps them too, without its grant,
with keepApps, below), and moving or handing an instance to
another organization turns its team grant into the target’s app team or org.
The owner does not always reach their app. An organization’s app is
reached only by the organization’s current members and its guests: its owner and
the named members stop reaching it, and receiving its events, once they
leave or are removed (the grants keep their names, so being added back to the
organization restores it). An app on a team is reached by its owner only while
they are in that team, as owner_in_org asks of the organization: an owner who
leaves the team, is removed from it, or loses it when an open team is closed
without them, stops reaching it (a person removed from Chat’s app team no
longer reaches the channels they created), and has it back once they are in
the team again. Likewise an instance only named people reach (a DM, a private
channel) of a package that has an app team in its organization is reached only
by those of its owner and named members who are in that app team (SystemState::app_team_of):
someone removed from Chat’s team, who leaves it, or who loses it when it
closes, is out of Chat’s DMs too, and has them back once in the team again. An
instance of a package with no app team there keeps its names alone. A
caller who does not reach it gets 404,
so its existence is not disclosed; with no credential, 401. The check reads
fresh system state, so removing someone from an organization or team holds on
every node before their next request (Reads of the system
state).
An organization’s app is managed by its owner only while they are a member
of the organization (member or above, as owning an app there takes;
SystemState::owner_acts). An owner who leaves, is removed or is made a guest
keeps their name on the record but none of its powers: changing its access
(so they cannot grant anyone to reach it again), its metadata, transferring
or deleting it, upgrading it or making an upgrade key for it, uploading files
to it or deleting its blobs. The organization’s admins (and its owner) still
transfer it to a member or delete it, so an organization cleans up an app whose
owner left; POST /apps/{app}/transfer is open to them too, with their own
passkey. Likewise, an app on
a team is managed by its owner only while they are in that team: out of it,
they keep their name on it and none of the powers above, and the
organization’s admins (or whoever manages the team’s apps) transfer it. The
rules are judged where each command applies; SetAccess, SetAppMetadata,
TransferApp, DeleteApp, UpgradeApp and CreateApiKey entries an earlier
release logged replay as that release judged them (ownership alone, and no
admin transfer, without owner_in_org; the owner without the team, without
owner_in_team); the API marks new ones.
A member whose direct row in the app’s team is read-only still reaches
the app, but only its views run for them: any other call is refused with 403
before it runs. A blob upload by them is refused
before it starts.
Organizations
Section titled “Organizations”POST /orgs { name, capabilities? } creates an organization with its creator as owner.
capabilities (bits) sets what members can do unless set for them
(defaultCapabilities), in the same CreateOrg entry, so an app need not
follow with a second call (409 FEATURE_NOT_ACTIVE below cluster version
1.0.0-rc.29); absent, a new organization’s default stands.
Its name is one line of 1 to 64 characters with no space at either end
(400 otherwise). The owner or an admin renames it, with a passkey: POST /orgs/{org}/name { name } (412 CONFIRM_REQUIRED first; the consent is
org:<org> / __rename_org / { name }, SystemCmd::RenameOrg), answered
with { orgId, name }; a member below admin gets 403, and someone outside
it 404. Nothing keeps a copy of the name, so GET /orgs/{org}, the orgs
of /auth/me and an invite redeemed after the rename all answer the new
one. A name is checked where the command applies: a CreateOrg an earlier
release logged (without name_fits) replays taking any name, and an
organization keeps the name it has until renamed.
Where an instance goes
Section titled “Where an instance goes”Every app is in an organization. An organization is an organization: a person’s
own is just one with a single member, its owner. From cluster version
1.0.0-rc.32 (Feature::OrdinaryOrgs) a sign-up makes none; an account’s
organizations are those it creates (POST /orgs, or with an instance below) or
is invited to.
A package’s developer says in its signed manifest which organization an instance
goes into (instanceOrg, kept on the release’s record, PackageVersion::instance_org;
meroctl app pack --instance-org or instance-org in
[package.metadata.calimero]):
instanceOrg |
POST /apps naming org |
naming none | newOrg: { name } |
|---|---|---|---|
standalone |
400 STANDALONE_INSTANCE |
a new organization, made with the instance | a new one, so named |
org |
that organization | the creator’s only one; 400 ORG_REQUIRED with several, 409 NO_ORGANIZATION with none (create one, or accept an invite) |
400 ORG_INSTANCE |
either (default, and a raw bundle) |
that organization | the creator’s only one; with none a new one; 400 ORG_REQUIRED with several |
a new one, so named |
The creator’s organizations are those they are a member or more of. A new
organization is an ordinary one owned by the creator, approving the release of
the node it was made through and counted against maxOrgsPerAccount; it is
named newOrg.name, else the instance’s name made to fit (one line, at most 64
characters), else the package’s id. It is written before the instance (two
entries): a failure after it leaves the organization in place, as a unit’s
member made before a failure stays. The people of a standalone instance are
invited into its organization. An instance from a deployment follows its
release’s mode the same way; a unit’s members always join their instance’s
organization. A release recorded before the node kept the mode is read from its
.mpk; installing it again records it.
Personal organizations
Section titled “Personal organizations”Before 1.0.0-rc.32 (below that cluster version) a
sign-up made the account’s personal organization in the same entry
(CreateAccount { personalOrg }, named Personal) and an instance naming no
organization went there. Such an organization keeps its personal: true flag
(in GET /orgs/{org}, the orgs of /auth/me), and entries logged before the
version replay as they applied. From the version on it is an organization like
any other: no new one is made (CreateOrg { personal } is refused, 409 PERSONAL_ORGS_ENDED, and a sign-up’s seed is dropped), it counts against
maxOrgsPerAccount (an account above the limit keeps its organizations; only
creating one more is refused), an app there is transferred only to a member
(as everywhere: 400 REJECTED), a deployment’s report names it, and a consent
request with no scope ("scope": "account") stands for the account’s only
organization. One thing stays: an instance there still reaches the accounts it
names without making them members, whatever its package’s manifest says about
guests.
Apps outside any organization were removed in a hard cutover (1.0.0-rc.20): data holding one is not read.
Members have one role each, ordered guest < member < admin < owner:
| Role | May |
|---|---|
guest |
Once the organization has app teams, reach only the apps of the teams they have a direct row in (no org-access app, no open top-level team by inheritance); before that, its org-access apps as before. Always see only the people of their teams |
member |
Also own apps in the organization and create top-level teams if they hold CREATE_TEAM |
admin |
Manage members and their roles (below owner), capabilities, teams, organization metadata; delete the organization’s apps; approve releases, upgrade apps and approve outbound hosts (they hold every capability) |
owner |
Everything, plus ownership and deleting the organization. Release approvals are also open to APPROVE_RELEASES holders, outbound approvals to MANAGE_APPLICATION holders (see Capabilities); app upgrades are the owner’s and admins’ alone |
There is exactly one owner. SetOrgRole { role: owner } by the owner moves
ownership and makes the previous owner an admin; the owner cannot be removed,
only replaced. Leaving is removing oneself. Removing a member clears their
capabilities, metadata and every team row they had. DELETE /orgs/{org}
(owner, with a passkey step-up) deletes the organization with its teams,
invites and apps, and unbinds the package signing keys it published
(Publishers).
An organization also keeps metadata for its apps and frontends to read (admins,
or members holding MANAGE_METADATA), per-member metadata (the member or an
admin), the mero-tee releases its APPROVE_RELEASES holders approved, the
outbound prefixes its MANAGE_APPLICATION holders approved, and its recent
upgrade runs. An organization may also be a publisher: a package signing key is
bound to it by the key’s own signature (APPROVE_RELEASES holders send the
binding), and it then approves releases, and (where the package says so) runs
upgrades, for every instance of that key’s packages
(Publishers). Each metadata value is at most 16 KiB of JSON. Any
member reads, with GET /orgs/{org}/apps, the apps they reach or manage
there with the release each runs and its last upgrade (who, of which kind),
the releases that govern each app, and the releases the cluster’s nodes run
(Reading the approvals).
Members’ security
Section titled “Members’ security”The owner and admins read what tells them a member may be locked out, with
GET /orgs/{org}/members?detail=security (their own session on the
cluster’s origin; never an API key or a package-bound session). For each
member: the self-set name (memberMetadata.name), role, the teams they
are in, passkeys (1, 2 or "3+": whether they have a backup, not how
many devices they own), recoveryCode (set or not), lastActiveDay (the UTC
day of their latest sign-in or session exchange; null when the node knows
neither) and sessions (how many live sessions they hold).
| Reader | Sees | Never |
|---|---|---|
| The account holder | Everything about their own account: passkeys with labels and times, sessions, activity (/auth/me, /auth/sessions, /auth/activity) |
- |
| The organization’s owner and admins, about its members | The fields above | Credential ids, passkey labels (names people choose for their devices), sign counts and times, sessions, origins, activity, a recovery under way |
| A member below admin | Nothing new (403) |
as above |
| A deployment’s managers, about customer organizations | memberCount and activeMembers30d per organization (GET /deployments/{id}/orgs) |
Any account, name or per-member fact |
| The operator | Nothing new: the Ops API has no read path into accounts | Anything per account |
A removed member leaves the listing at once, and someone outside the
organization is answered as if it did not exist (404).
Teams (types::Team; meroctl’s groups) nest (parent), move
(UpdateTeam { parent }, never under themselves), and are one of two kinds:
- Open (
join: everyone): whoever reaches the parent team — at the top, the organization — is a member too, unless they were deniedJOIN_OPEN_TEAMSthere. Membership flows down an unbroken chain of open teams. - Restricted (
join: invite): only direct rows. A restricted team is a wall: nothing flows through it.
A direct row has a role (lead, member or read-only) and capabilities.
A team’s creator leads it. Whoever leads a team, or an ancestor team, or is an
organization admin, manages it: renames it, adds and removes members,
creates teams under it, moves it within what they manage, and deletes it. A
member who writes a team (a row that is not read-only, or inheritance into an
open team) and holds CREATE_CHILD_TEAM there also creates a restricted
team below it, and leads that one: this is how any member of an app’s team
makes a private channel. An app team holds CREATE_CHILD_TEAM in its default
capabilities, so it is on unless an admin turns it off; a CreateTeam entry an
earlier release logged replays with only the parent’s managers creating below
it (member_child_teams).
- Removing someone from a team, or their leaving it, also removes their direct
rows in every team below it, so a restricted child team (a private channel
under an app’s team) does not keep them in. Closing an open team (
POST /orgs/{org}/teams/{team} { join: invite }) does the same for whoever loses it then, being in it by inheritance alone: their rows below it go, and they are not barred, so opening it again lets them back into the team (not into the channels). AnUpdateTeaman earlier release logged replays keeping those rows (close_drops_below). - A member who leaves a team, or whom a manager removes, does not come back by
inheritance (
Team::removed), so leaving an open team sticks. They return only when a manager adds them again or they redeem an invite that names the team; they cannot rejoin by themselves. - A member may join an open team they already reach as a plain member row, or leave any team themselves.
- One account’s rows in several teams of the organization are set in one log
entry with one passkey approval (
POST /orgs/{org}/members/{account}/teams { teams: [{ team, role?, capabilities? }] },SystemCmd::SetTeamMembers, consent__set_team_members { account, teams }): Calimero Home’s “give all apps” gives a member every app team at once. They are taken, or left, the same way (DELETEwith{ teams: [team] },SystemCmd::RemoveTeamMembers,__remove_team_members { account, teams }). Each team is judged as its own team-member change would be, in order, and the entry applies all or nothing: one team the caller may not change refuses the whole batch. A batch names 1 to 64 teams (MAX_TEAM_BATCH), each once (400 BAD_TEAMS). - Deleting a team deletes the teams below it and the apps deployed to them:
every instance whose only member grants are those teams’ (its team grants all
go, and no
orggrant), even one that also names guests or other accounts. An instance another team or the organization admits only loses the deleted teams’ grants. When there are apps, it takes the deleter’s passkey:DELETE /orgs/{org}/teams/{team}answers412 CONFIRM_REQUIREDwith theappsandkeepAppsin its details, and the consent (__delete_team { team, apps }) names exactly those, so an app added since is not deleted on an old approval. - Keeping the apps (
DELETE /orgs/{org}/teams/{team} { keepApps: true },meroctl team delete --keep-apps,DeleteTeam { keep_apps },Feature::KeepTeamApps, cluster version 1.0.0-rc.33, else409 FEATURE_NOT_ACTIVE): those instances stay. Each loses the deleted teams’ grants and keeps its others (named members, guests,anyone, public links); one with no grant left has an empty grant list, which only its owner reaches (ateaminstance included). The consent states it (__delete_team { team, apps, keepApps: true }), and the answer lists them inkeptApps(apps, the deleted ones, is empty). Without the flag, or absent in an entry an earlier release logged, they are deleted as before. - Reads are filtered: a team someone neither reaches nor manages is left out of
GET /orgs/{org}and answers404on its own route. - A team keeps metadata the app defines (a folder’s name and colour), set by
those holding
MANAGE_METADATAfor it. - A team may hold default capabilities (
Team::default_capabilities): everyone in the team holds them there on top of their organization-wide ones, unless their row sets its own. Set withPOST /orgs/{org}/capabilities { team, capabilities }(noaccount) by whoever manages the team or holdsMANAGE_MEMBERSthere, with a passkey (__set_default_capabilities { team, capabilities }). This is how “members may invite others to this app” is switched on per app.
An app deployed with access: team must be created by someone who writes that
team (a member whose row is not read-only).
App teams
Section titled “App teams”An app team is a top-level team whose metadata marks a package:
metadata.app = { package, name } (Team::app_package). An organization has
at most one per package: marking a second is refused. Only an owner or admin
makes, changes or drops the mark: installing an app in an organization is
theirs. The app’s instances use access: team on its app team, or on a
restricted team below it (a private channel). The organization’s mode is
derived from its app teams, never stored, and answered as mode on
GET /orgs/{org} and GET /orgs/{org}/app-teams:
| Mode | When | Means |
|---|---|---|
legacy |
No app team | Apps use org access, as before app teams. Behaves as standalone. |
standalone |
Every app team open | Everyone in the organization has every app; members may invite to the app (the team’s default INVITE_MEMBERS) |
shared |
Some app team restricted | Each app lists its people; invites name the app team; only leads and admins invite unless an admin turns on the team’s default |
POST /orgs/{org}/app-teams { apps?: [{ package, name?, instances?, join?, keep?, childTeams? }], shared? }
(an owner or admin, with a passkey: __scope_apps { apps, shared },
SystemCmd::ScopeApps) gives apps their own access lists in one log entry.
For each package (absent: every package with an org-access instance in the
organization) it finds or makes the app team (its creator leads a new one),
gives a plain row to every member who reaches the instances now, and moves the
instances (absent: every org-access instance of the package) to access: team on it. shared (absent: whether the organization then holds two app
teams or more) closes every app team, everyone it held kept as a direct row,
and takes INVITE_MEMBERS out of its default. Nobody loses an app. A new
app team’s default holds CREATE_CHILD_TEAM in either mode (INVITE_MEMBERS
too while standalone), so its members make private channels below it. App
teams made before keep the default they had (nothing changes on replay or as a
side effect) until an admin turns it on: a package’s childTeams: true adds
CREATE_CHILD_TEAM to its app team’s default and to every row there that sets
its own capabilities (a row added one by one keeps what it got then), and
childTeams: false takes it out of both. With instances: [] the step moves
no instance, and naming childTeams (as naming join) leaves shared,
absent, meaning “no other team”, so POST /orgs/{org}/app-teams { apps: [{ package, instances: [], childTeams: true }, ...] } turns it on for every
app team named, with one passkey, and changes nothing else.
To keep one app apart and leave the others as they are, a package names its
own join in the same request: invite closes that app team alone, in the
same log entry that fills its rows, and everyone opens it again (shared,
absent, then changes no other team; shared: true with an everyone is
refused). A close keeps, by default, everyone who reaches the app then, each
as a direct row. With keep: [account, ...] (members of the organization
only) the team’s leads and those accounts keep it, each with a row, and
everyone else in it, by a row or by inheritance, loses it, together with their
direct rows in the teams below the app team (its private channels), as a
removal from the team takes them; they are not barred, so opening the team
again lets them back in. Each package’s answer names its team’s join after the step and
how many people it dropped. A single team also opens or closes with POST /orgs/{org}/teams/{team} { join } (MANAGE_VISIBILITY, an admin’s anywhere),
which fills no rows: closing that way, only the existing direct rows stay, and
whoever loses the team loses their rows in the teams below it too.
GET /orgs/{org}/app-teams lists, to any member, each app team’s package, id,
name, join, member count, default capabilities and whether the caller is in
it or manages it (a guest: only their own).
Every app added later
Section titled “Every app added later”In an organization that keeps its apps apart, a new app’s team holds only the
people named when it is made. A member may instead hold a standing grant,
every app added later (Org::all_apps, allApps on GET /orgs/{org}):
each app team made from then on gives them a plain row, whoever else it
names, so they reach every new app, open or closed. That is an app team made
by ScopeApps (closed with a keep list too: they are kept), one a move
makes in the organization (Moving an app), and a team an
admin marks as an app team (unless they were removed from that team). It
gives nothing in an app team already there: an admin adds them to those as
anyone else.
The grant is the owner’s or an admin’s to give, with a passkey: on an invite,
POST /orgs/{org}/invites { ..., allApps: true } (the consent’s arguments
then name allApps: true; 403 below admin), which gives it to whoever
redeems it, and later, POST /orgs/{org}/all-apps { account, allApps }
(__set_all_apps { account, allApps }, SystemCmd::SetAllApps; false
stops it, the rows already made stay). A member redeeming an allApps
invite gets the grant, which spends a use. It ends with their membership:
leaving, removal, or a recovery that removes them. ScopeApps, MoveApp and
UpdateTeam carry all_apps_rows, which the API always sets; entries an
earlier release logged replay making no such rows.
While an organization has app teams, creating the first instance of a package
that has none there is an admin’s. In a
shared organization a member sees, in GET /orgs/{org}, only the people of
the teams they are in and its owner and admins; a guest sees only their teams’
people in every mode; owners and admins see everyone. Calimero Home, the
portal that manages people, invites and apps across an organization, is one
first-party package every cluster installs; it uses these routes and needs
nothing else from the node.
Moving an app
Section titled “Moving an app”POST /apps/{app}/move { toOrg, bringMembers? } (SystemCmd::MoveApp, with a
passkey: <app> / __move { toOrg, bringMembers }) moves an app instance to
another organization in one log entry. Its data stays where it is: the same
group, replicas and state. Calimero Home’s “Merge organizations” moves every
app of one organization into another this way.
- Who: whoever manages the app where it is now (its owner while a member, or an admin there), as an admin or the owner of the target. Judged on the state of the moment, so a member removed from the source, or an admin of the target demoted, is refused.
- Payer: its file bytes, compute runs and quotas go to the target. A move
past the target’s file or compute quota is refused (
429 QUOTA_EXCEEDED), as is one to a target that approves none of the releases holding the app now. - Grants: an
orggrant, or ateamgrant on its package’s app team, becomes ateamgrant on the target’s app team of the package. The target’s is used, or made when missing: open, unless every app team of the target is restricted (shared: true), where it is restricted like its others; an app team an admin closed alone leaves it open. The mover leads a new one, whose default capabilities are any new app team’s (CREATE_CHILD_TEAM, andINVITE_MEMBERSwhile open). Alegacytarget, and a raw upload (no package), get anorggrant instead, so moving an app in never changes the target’s mode. Named people andanyonestay as they are, though only the target’s members (and its guests) reach it from then on; an instance only named people reach whose package has a closed app team in the target is reached there only through that team (see App access), so its owner and the people it brings get a row on it (below). An app on any other team (a restricted team below the app team, a plain team) is refused: that team’s leads, read-only rows and capabilities are grants of the source, which the target’s admins never saw. Give it anorgor app-team grant first. - Owner: stays, and must be a member of the target once the move is done, or the move is refused: an organization’s app is owned by one of its members, and only a transfer the owner or an admin consents to changes who that is. An owner who reaches the app now gets a row on the target’s app team, as an owner reaches and manages an app on a team only while in it.
bringMembers: every member of the source who reaches the app joins the target at their role there, capped atmember(a guest stays a guest; an admin comes in as a member, and the target’s admins grant more themselves), and gets a row on the target’s app team: the one anorgorteaminstance moves to, or, for an instance only named people reach (a DM, a private channel), its package’s app team there when that team is closed, so they keep reaching it (an open one needs no row). Someone already in the target keeps their role. An app team made in the target gives its members who hold every app added later a row too. AMoveAppan earlier release logged (withoutaccounts_in_app_team) replays giving its named people no such row.- Invites: the source’s invites naming the team the app leaves are revoked once no app of the source is on that team.
The answer is { appId, from, org, grants, created, added, revokedInvites }.
A node from before this route answers 404, which clients take as “not
supported here”.
Capabilities
Section titled “Capabilities”Beyond their role, a member holds capability bits (types::caps, the
MemberCapabilities values): organization-wide, with a default the
organization sets, and per direct team row (a new row takes the member’s
organization value). Admins and team leads hold them all where they manage.
| Bit | Name | Checked by the node |
|---|---|---|
1 << 0 |
CREATE_APP |
Creating an app in the organization (on its team, or org-wide) |
1 << 1 |
INVITE_MEMBERS |
Minting an invite (org-wide, or on each team it names, where a team’s default capabilities count) |
1 << 2 |
JOIN_OPEN_TEAMS |
Inheritance into open teams (granted by default) |
1 << 3 |
MANAGE_MEMBERS |
Adding non-lead rows and setting capabilities in a team |
1 << 4 |
MANAGE_APPLICATION |
Approving the organization’s outbound hosts (org-wide only). Upgrading its apps and its upgrade runs are its owner’s and admins’ alone from 1.0.0-rc.33 (App upgrades); before, this capability gave them too (on the app’s team, or org-wide) |
1 << 5 |
CREATE_TEAM |
Creating a top-level team (or moving one to the top) without being an admin |
1 << 6 |
DELETE_TEAM |
Deleting a team one does not manage |
1 << 7 |
MANAGE_VISIBILITY |
Switching a team between open and restricted |
1 << 8 |
MANAGE_METADATA |
Organization and team metadata |
1 << 10 |
APPROVE_RELEASES |
Approving (or withdrawing) the mero-tee releases that hold the apps the organization governs: those of the packages it publishes, and its own apps of packages whose key is not bound; and binding a package signing key to the organization (org-wide only: a team grant does not reach it) (Release approvals) |
1 << 11 |
CREATE_CHILD_TEAM |
Creating a restricted team below a team one writes, without managing it (the creator leads the new team); in an app team’s default |
Bit 9 is unused: v1’s MemberCapabilities spends it on CAN_AUTHOR_ON_BEHALF,
so a client that sends v1’s ALL grants nothing new by accident. A grant is
POST /orgs/{org}/capabilities { account, capabilities } by an admin, with
their passkey (as every membership change: roles, removals and leaving, team
rows; 412 CONFIRM_REQUIRED first); GET /orgs/{org} lists who may approve releases (releaseApprovers).
Invites
Section titled “Invites”An app’s own frontend cannot call these routes; it asks the node’s consent page
to mint (createInvite) or accept (acceptInvite) an invite with the person’s
passkey (The consent page).
POST /orgs/{org}/invites { role, teams?, ttlSecs?, uses?, allApps?, capabilities? } returns a token
inv_…, after the inviter approves it with a passkey (412 CONFIRM_REQUIRED
first; the consent binds { inviteKey, role, teams, expiresAt, uses }). Only
the token’s Ed25519 public key is stored (inviteKey, the key whose seed is
SHA-256("calimero.invite.v1\0" ‖ token)). An invite expires (7 days by default) and
admits uses accounts (1 by default). Its role may not exceed the inviter’s and
is never owner. Only the owner or an admin mints one with allApps
(Every app added later). An inviter below admin needs INVITE_MEMBERS on each team the
invite names (organization-wide when it names none), and may name only teams
they see (a member of, or a manager): an organization-wide grant does not open a
restricted team they are not in.
capabilities (bits) is what a new member holds as their own setting
(Org::capabilities) once they redeem it, in place of the organization’s
default; a member already in keeps theirs. An inviter below admin may give
only bits they hold organization-wide (403 CANNOT_GRANT_UNHELD, judged by the
log too, so every node agrees; bits no capability has are 400 UNKNOWN_CAPABILITIES); the owner and admins hold every bit. The consent’s arguments
then name capabilities, and the invite’s earlier shape (none) is unchanged
(409 FEATURE_NOT_ACTIVE below cluster version 1.0.0-rc.29).
POST /invites/{token}/redeem, by a signed-in person (no passkey prompt): the
node signs the redemption with the token’s key, which every node checks
where it applies, so a node that saw only the log cannot redeem an invite. It adds them at the invite’s
role (or keeps a higher role they already have) and gives them a plain row in
each named team. Only a redemption that does one of those spends a use: an
account already in the organization at the invite’s role or above, and in every
team it names (an owner opening their own link, say), gets the organization back
and leaves the use for the person the invite was made for. The last use removes
the invite; redeeming it after that, or after its organization is deleted, is
refused 400 REJECTED (“this invite was used up, revoked or never existed”), and
past its expiry “this invite has expired”. GET /orgs/{org}/invites lists the
pending invites the caller may revoke (key, role, teams, uses left, expiry,
creator and creation time; never a token): an admin all, a creator their own,
a team’s manager those naming only teams they manage. DELETE /orgs/{org}/invites/{inviteKey} revokes one, with the same rule and a passkey
(__revoke_invite { inviteKey }); an invite the caller may not see is 404.
Invites made before record no creator. A redemption an earlier release logged
replays as that release applied it (it spent a use whatever it changed): the
API marks new ones (RedeemInvite { free_when_unchanged: true }). In the same
way, a CreateInvite, RemoveTeamMember or DeleteTeam an earlier release
logged replays without the rules above (the teams the inviter sees, the rows
below, the passkey for apps); the API marks new ones (teams_seen, subtree,
apps_need_consent).
Guests
Section titled “Guests”A guest of an instance is an account invited to that one instance (and the
apps its unit created for it) without joining its organization: an account
grant naming someone who is not a member. From cluster version 1.0.0-rc.33 (Feature::Guests) a
guest reaches the instance when both switches allow guests, the stricter
winning:
| Switch | Where | Default |
|---|---|---|
| The developer’s | the release’s signed manifest, guests: "allowed" | "forbidden" (meroctl app pack --guests; kept on PackageVersion::guests: a release recorded before the node kept it, a raw bundle, takes none until the same .mpk is installed again) |
forbidden |
| The organization’s | allowGuests, an admin policy set by its owner or an admin with a passkey: POST /orgs/{org}/settings { allowGuests } (org:<org> / __set_org_settings / settings, SystemCmd::SetOrgSettings); GET /orgs/{org} shows allowGuests: false when off |
allowed |
A named account that is a member is a named member, with the member semantics
above (its app team included). Access is judged fresh on every request, so
taking a guest’s grant away (POST /apps/{app}/access, by whoever may change
the instance’s access), turning the organization’s switch off, or an upgrade to
a release that forbids guests holds from the guest’s next request. An instance
in an organization made as a personal one before 1.0.0-rc.32 keeps its named
accounts’ reach whatever the switches say (Personal
organizations).
What a guest may do: what any account that reaches the instance may (call its
methods and views, receive its events, read and upload its blobs, as a named
member could), nothing more. They are not a member: they see none of the
organization’s members, teams, other apps, invites, settings, usage or reports
(404 as to a stranger), the app’s code sees no role for them
(env::org_role is None), and they never manage the instance, approve its
upgrades, set its secrets, list or export its sealed files (/files is the
organization’s members’ and its owner’s), or delegate, link or move it.
GET /apps/{app} shows a guest only their own grant.
Unit members: a guest of an instance reaches the apps its unit created for it
(AppRecord::links, transitively), judged by the instance’s grants and switches;
an attached app is not part of it.
Instance invites
Section titled “Instance invites”An instance’s managers (whoever may change its access) invite people with a
link, like an organization invite but for one instance, on any instance: POST /apps/{app}/invites { ttlSecs?, uses?, scope? } returns a token inv_… once
(412 CONFIRM_REQUIRED first; the consent is <app> / __create_app_invite / { inviteKey, expiresAt, uses, scope? }; only the token’s Ed25519 public key is
logged, SystemCmd::CreateAppInvite, which needs Feature::AccessGrants too).
It is made whatever the guest switches say now: whether a guest may come in is
judged when someone redeems it. POST /invites/{token}/redeem (the same route as an organization invite; the node
tells them apart) adds an account grant for the redeemer, with the invite’s
scope (RedeemAppInvite, signed with the token’s key): a guest, or a named
member when they are a member of the organization, never a new member. It answers { app, org, member }; one already named spends no use. A
member of the organization (member or above) is always named; anyone else is
admitted as a guest only while the instance’s release says guests: allowed
and the organization’s allowGuests is on, judged on the state the redemption
applies to, so a switch turned off after the invite was made holds (409 GUESTS_NOT_ALLOWED; the invite and its uses stay). GET /apps/{app}/invites lists the pending ones (key, uses left, expiry, creator,
scope; never a token) and DELETE /apps/{app}/invites/{inviteKey} revokes one
with a passkey (__revoke_app_invite { inviteKey }). Deleting the instance
drops its invites. Bounds: MAX_APP_INVITES_PER_APP (64) pending per instance,
MAX_APP_INVITES (10 000) in the cluster, MAX_APP_INVITE_USES (1 000) uses
and MAX_APP_INVITE_TTL_SECS (90 days) each, MAX_ACCOUNT_GRANTS (1 000) names
per instance and MAX_GRANT_SCOPE_BYTES (256) per scope. The consent page’s
acceptInvite shows an instance invite as joining the app of a package in an
organization, as a guest or, to a member, as the member they are.
The platform admits, the app scopes
Section titled “The platform admits, the app scopes”The node decides only who reaches an instance. Anything finer, such as which
channel of a chat a partner may read, is the app’s own rule, but the platform
carries it for the app: an invite, and the account grant it makes, may carry a
small opaque JSON scope the app defines ({"channel":"partners"}), which the
node stores, shows to the instance’s managers and never reads. The app reads the
caller’s scope with env::grant_scope() (WIT context.grant-scope, 0.5.6: the
grant on the instance, or on the instance whose unit made it; none for anyone
not named, and in a compute run). To let a partner into one channel of a chat,
its managers invite them with that scope; the chat reads it and keeps them to
that channel. A grant without a scope is the app’s whole. Changing the scope is
changing the grant (POST /apps/{app}/access). A component built before 0.5.6
cannot read a scope, so it admits the person to all of it.
Public links
Section titled “Public links”A public link lets anyone holding its token call one instance’s
#[app::public] methods as an anonymous visitor, without an account and
whatever the instance’s other grants (from cluster version 1.0.0-rc.32,
Feature::PublicLinks). It is the third kind of grant beside member and named
grants: a link grant in the instance’s list (Grant::Link: its key, label,
expiry, rate, creator), which admits no account, only its visitors. It is made
and revoked only on its own routes, each with a passkey; POST /apps/{app}/access keeps an instance’s links as they are, and refuses one it does not already hold. GET /apps/{app} shows
link grants only to whoever may change the instance’s access. Whoever may change
the instance’s access makes one with a passkey: POST /apps/{app}/public-links { label?, expiresAt?, ratePerMinute? }
(412 CONFIRM_REQUIRED first; the consent is <app> / __create_public_link / { linkKey, label, expiresAt, ratePerMinute }) answers { link, token } once;
only the token’s Ed25519 public key (link) is logged, so a node that saw the
log cannot let anyone in. GET /apps/{app}/public-links lists them (never a
token) and DELETE /apps/{app}/public-links/{link} revokes one with a passkey.
A link lasts until revoked unless it names expiresAt; an instance holds at
most 16 (MAX_PUBLIC_LINKS_PER_APP); deleting the instance drops them. The
organization’s owner or an admin turns links off with POST /orgs/{org}/settings { allowPublicLinks: false }: no new link, and existing ones admit nobody at the
visitor’s next call (allowPublicLinks in GET /orgs/{org}).
A visitor holds its own Ed25519 key (a browser keeps its seed in local
storage) and sends, on every request, Authorization: Bearer vis1.<token>.<key>.<at>.<signature>: its public key (64 hex) and its signature
over "calimero.visitor.v1\0" ‖ link ‖ 0 ‖ key ‖ 0 ‖ at, at within 5 minutes
of the node’s clock (mero-js client.useVisitor({ link, seed }), the Rust
client’s use_visitor). Nothing about a visitor is logged. The node admits it
only to that instance’s calls and views of #[app::public] methods
(403 for any other method, 403 VISITOR_ONLY on every other route, 404 for
another app, 401 once the link is revoked, expired or turned off), at most
ratePerMinute calls a minute per visitor on each node (429 TOO_MANY_VISITS;
default 60, at most 600), besides a method’s own rate. The app sees
Caller::Visitor { link, key } (WIT context.visitor, 0.5.6; a component
built before sees Caller::Public), so it can tell visitors apart and count
one answer per visitor; it has no org role, and the SDK’s guards refuse it.
Recovery
Section titled “Recovery”An organization may hold a recovery key (Org::recovery): an Ed25519 key
whose 32-byte seed its owner keeps offline; the organization stores only the
public half (publicKey, base64url). It is set at creation (POST /orgs { name, recoveryKey }) or by the owner later, with a passkey (POST /orgs/{org}/recovery { publicKey }, consent org:<org> / __set_recovery_key / { publicKey }; null removes it). An organization created before recovery
keys has none until its owner sets one.
An organization’s owner is an account, and an account acts only with its own passkeys. An owner who loses every passkey can no longer act for the organization, and nobody can act for them: an admin cannot change ownership, no Ops route touches an organization, and every decision carries its maker’s proof. Recovery moves the organization’s ownership to another account, the one the person signs up with a new passkey, after a delay during which the current owner can cancel. It acts on the organization only: one organization’s seed reaches nothing outside it (not the owner’s other organizations), and an account that owns several sets a key on each. To get the account itself back, see Account recovery.
| Step | Route | Who | Proof logged | Effect where it applies |
|---|---|---|---|---|
| Set or rotate | POST /orgs/{org}/recovery { publicKey } (null removes; 412 first) |
The owner | Passkey consent over org:<org> / __set_recovery_key / { publicKey } |
SetRecoveryKey: replaces the key and cancels a pending recovery |
| Set at creation | POST /orgs { name, recoveryKey } |
The creator | The session, as for any new organization | The new organization holds the key |
| Start | POST /orgs/{org}/recovery/start { nonce, signature } |
Any signed-in account (the new one) | The seed’s signature over recovery_message(org, account, nonce) |
StartRecovery: pending = { account, startedAt, readyAt = startedAt + 72 h } |
| Cancel | POST /orgs/{org}/recovery/cancel (412 first) |
The owner | Passkey consent over __cancel_recovery / { account } |
CancelRecovery: nothing pending |
| Finish | POST /orgs/{org}/recovery/finish (412 first) |
The pending account, at or after readyAt |
Passkey consent over __finish_recovery / { org } |
FinishRecovery: the account becomes the owner; every previous owner leaves the organization and its teams, and the apps they owned in it become the new owner’s |
recovery_message is "calimero.org-recovery.v1\0" ‖ org ‖ 0 ‖ account ‖ 0 ‖ nonce (calimero_identity::recovery_message). The client derives the public
key and signs on the person’s machine, and only the signature travels. It binds
the account the organization goes to, so a node that saw the log cannot
redirect it, and it is spent once (used_proofs). It is checked against the
organization’s current key, at the API and again where the command
applies, on every node, so rotating the key makes every signature under the old
one fail.
Limits. RECOVERY_DELAY_SECS (72 hours) is judged at the commands’ own
times (stamped by the node that takes the request, replicated with it), never
at apply. One pending recovery per organization: a second start is 409 RECOVERY_PENDING until the owner cancels or the pending one finishes, so a
seed holder cannot replace a pending recovery with their own. The nonce is at
most MAX_RECOVERY_NONCE_BYTES (64); the key and signature text are bounded
before decoding (MAX_RECOVERY_KEY_CHARS, 44; MAX_RECOVERY_SIGNATURE_CHARS,
88). A wrong seed is refused at the API before anything is logged, and no
counter limits attempts: guessing a 256-bit seed is not a threat a counter
changes. An unknown organization, one with no key and a wrong signature all
answer 403 WRONG_RECOVERY_KEY, so an outsider learns nothing about which
organizations exist or hold a key.
What members see. GET /orgs/{org} shows members recovery: { publicKey, setAt, pending } (absent when no key is set), so a client can warn every
member, the owner first, while a recovery is pending. The recovering account is
not a member yet; it reads the pending recovery’s times in the answers of
start and finish. Nothing about recovery is in the Ops API or
/ops/metrics.
| Who | Can they recover the organization? | What limits it |
|---|---|---|
| The operator | No | The seed never reaches a node; no Ops route starts, cancels or finishes a recovery, and the operator’s signature is not a recovery proof |
| A node, or anyone reading the log | No | The log holds the public key and spent signatures, each bound to one account |
| An admin or member | No | Setting, rotating and cancelling need the owner’s passkey; starting needs the seed |
| An account outside the organization | Only with the seed | The seed is the credential |
| Someone who stole the seed | Yes, unless the owner acts within 72 hours | Every member sees the pending recovery; the owner cancels with a passkey and rotates the key |
| The owner, every passkey lost | Yes | Sign up with a new passkey, start with the seed, wait 72 hours, finish |
| The owner, passkeys and seed lost | No | Nobody can |
A thief who already finished a recovery owns the organization; the delay and
the warning to members are the defence. Recovery never changes an account’s
passkeys: the previous owner’s account and its other organizations are as they
were. Organizations written before recovery keys hold none
(Org::recovery is left out when unset) until their owner sets one.
Recovering the data after every mero-kms replica is lost is a different mechanism: the recovery disk and its backup keys, below.
Backup key
Section titled “Backup key”The recovery disk (merod --recovery-dir) writes, every 5 minutes, on every
node that holds an app, the app’s state, the code it runs and its holder’s
slice of the system state, each sealed to the holder’s X25519 public key (HPKE)
and signed by the node’s attested receipt key
(Recovery files). The backup holder
is whoever upgrades the app (SystemState::backup_holder): the operator where
it holds app upgrades, else the app’s organization, also for a package that
declares upgrades: publisher. An account’s own apps are in an organization
like any other app. No node ever holds a private half.
| Holder | Read | Set |
|---|---|---|
| An organization | GET /orgs/{org}/backup-key (any member) |
POST /orgs/{org}/backup-key { publicKey } by an org-wide MANAGE_APPLICATION holder, with a passkey (org:<org> / __set_backup_key / { publicKey }, 412 first) |
| The operator | GET /ops/backup-key |
POST /ops/backup-key { publicKey }, signed with the operator key (operator / __set_backup_key / { publicKey }; The operator) |
publicKey is 64 lowercase hex characters (400 BAD_BACKUP_KEY otherwise).
The answer is { holder, key: { publicKey, setAt, setBy } | null, apps },
apps being how many apps’ backups open with it. Setting a key is the
SetBackupKey command, gated by the backupKeys feature (1.0.0-rc.20,
The cluster version); the owner-side
routes answer 403 where the operator holds app upgrades. Until a key is set,
nothing is written for that holder’s apps.
An organization’s apps come back on a cluster that does not hold them with
POST /recover/holder: the holder’s own device opens the data keys of its
files with its private key and sends them over the sealed channel, and the
operator admits the import with its signature (SystemCmd::ImportHolder). The
organization, its people (who sign in with the passkeys they had), its apps and
its backup key come back; it is refused where any of them is on the cluster
already (Recover after every key service is gone).