Identity and tenancy
Cheetah uses several identities because a distributed client has several lifetimes and scopes. The authenticated principal protects data and routing. A logical client remains addressable across reconnects. A runtime instance identifies the process or service-worker lifetime that actually attempts a command. Command and message identities correlate work and returned evidence.
Treating these values as interchangeable breaks replacement safety or isolation. The table below is the shortest useful map.
Identity map
| Identity | Lifetime and scope | Created or trusted by | Primary use |
|---|---|---|---|
| user ID | stable application user identity | authentication boundary | dedicated-principal routing and the user axis of shared tenancy |
| tenant ID | stable organization or isolation identity | authentication boundary | outer scope for mutually untrusted users sharing infrastructure |
| effective principal | one authenticated routing and storage scope | server authentication path | prefixes streams and scopes registry, dispatch, correlation, history, and deduplication |
client_id | stable logical installation within a principal | client installation, accepted within authenticated scope | application addressing and reconnect continuity |
instance_id | one running client lifetime | client runtime | attempt fencing and replacement detection |
command_id | one server-issued action | application/server path | delivery, acknowledgement, progress, result, and recovery correlation |
message_id | one client HTTP delivery | client runtime | retry deduplication and retained-message identity |
| context and target IDs | platform or product-defined scope | owning client/runtime adapter | browser windows, tabs, pages, workers, machines, or product targets |
Human-readable account names, emails, slugs, and external identity-provider subjects are useful metadata, but they are not Cheetah routing identities. Keep them in the product's account model and map them to canonical identities at the trusted authentication boundary.
Dedicated-principal mode
Ordinary nodes authenticate one canonical user. That user ID is the effective principal for routing and storage. A command addressed to client_id="browser-main" therefore means that logical client inside this authenticated user's scope, not a globally unique browser client.
Dedicated mode is appropriate when each deployment or authenticated surface already separates mutually untrusted organizations, or when the product does not place multiple tenants in one shared Cheetah data plane. It does not require a tenant claim.
Shared-tenancy mode
When mutually untrusted tenants share a Cheetah deployment, the authentication path proves both a canonical tenant ID and a canonical user ID. Cheetah forms one effective principal:
ten_11111111-2222-4333-8444-555555555555@usr_aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeeeThe server composes this value exactly once from validated leaf identities. Clients and application callers do not submit a free-form combined principal. Every participating role uses the same effective value so the same inner user ID in two tenants still produces separate routes, streams, correlations, and retained history.
Shared tenancy is not enabled by adding a tenant_id field to ordinary nodes. The dedicated create_shared_tenant_nodes() path audits the selected components, enables tenant-required boundaries, and returns a restricted application surface that accepts authenticated tenant proof rather than arbitrary identity strings.
Transport and body identities
The WebSocket hello carries an authentication credential. The WebSocket host verifies it and derives the trusted principal before registration. Each HTTP return is authenticated again by the HTTP host, which derives the same principal before calling the REST role.
client_id, instance_id, stream suffix, and correlation IDs remain in message bodies because they identify resources within that trusted scope. A user_id or tenant_id appearing only in a body never establishes authority. The WebSocket session also does not act as an implicit authentication grant for a later HTTP request.
Ownership and replacement
A logical client can reconnect while retaining its client_id. The same runtime retains its instance_id across a transport reconnect; a real runtime replacement creates a new one. At the first delivery attempt, Cheetah binds the command to the current instance. An acknowledgement from a later replacement cannot satisfy that earlier attempt.
Contexts and targets have their own platform lifetimes. Their ownership does not migrate by changing an identity in a message. State reports reconcile the current world, and the legacy ownership-change protocol is rejected.
Canonical identities and authentication defines which identifiers are trusted at each network boundary and which remain scoped message data.
Shared-tenancy composition explains the restricted factory, component audit, and effective-principal rules used when mutually untrusted tenants share one data plane.
Isolation guarantees and limits states what the audited composition isolates and which control-plane, product-data, and operational responsibilities stay with the host.