matrix/docs/client-registration-installation-domain.md

Client registration and installation domain

Ownership

client_registration_details
└── client_account (tenant)
    ├── client_license
    │   └── license_activation_key
    └── client_installation

• A registration is the legal contracting and billing entity.
• A registration may own multiple isolated tenants.
• A tenant belongs to exactly one registration.
• A tenant may have license history; installation uses a specific license.
• client_license.max_installations defaults to one and is cloud-enforced.
• A license key authorizes activation but is never a runtime credential.
• Every installation has a unique UUID and signing key pair.
• The installation private key never leaves the customer server.

Installation capacity

PENDING, ACTIVE, and SUSPENDED installations consume capacity. DECOMMISSIONED, REVOKED, and FAILED installations do not.

Registration must lock the applicable active license row, count consuming installations, and insert the new PENDING installation in one transaction. This prevents two concurrent requests from taking the same final slot.

Status transitions

PENDING -> ACTIVE -> SUSPENDED -> ACTIVE
                    |
                    +-> DECOMMISSIONED
                    +-> REVOKED

PENDING -> FAILED

• Suspension is temporary and continues consuming capacity.
• Decommission permanently retires a legitimate old server.
• Revocation permanently invalidates a compromised or prohibited server.
• Decommission and revocation require an actor, timestamp, and reason.
• Historical installation rows are retained for audit.

Activation credentials

The customer receives a client code and a random license activation key. The database stores only a strong key hash and a non-secret display hint. After validation, the cloud issues a single-use activation session with a short expiry and binds it to the intended installation UUID.

Client codes, tenant IDs, installation IDs, and key hints are identifiers, not authentication secrets.