Multi-Tenant and RBAC Model

1. Positioning

OrbitMesh uses multi-tenant isolation from the first production-ready design.

The model must support:

• personal workspaces.
• teams.
• enterprise teams.
• BYOH, managed, and shared nodes.
• per-user client access subscriptions.
• tenant-level resource governance.
• future SSO, OIDC, Feishu, WeCom, and GitHub Team integration.

The current implementation keeps the schema small and uses tenant, user, and membership as the runtime authorization boundary. The model must not assume one user equals one tenant.

2. Team Model

Team is the user-facing collaboration and account-management container.

Tenant is the resource isolation boundary behind a personal workspace or team workspace.

Target hierarchy:

Team
  -> Tenant
      -> Membership
          -> User
      -> Node
      -> Runtime Binding
      -> Endpoint
      -> Domain
      -> Certificate
      -> Client Access Subscription
      -> Traffic Policy
      -> Quota Policy
      -> Desired State
      -> Usage
      -> Audit Event

The current implementation may store only tenants and memberships. That is acceptable for the baseline as long as APIs and documents keep Team as the user-facing product concept.

Expected future Team fields:

• display name.
• owner account.
• billing account.
• identity providers.
• external group mappings.
• team-level audit and compliance settings.

Expected future Tenant fields:

• team_id.
• name.
• type.
• plan_id.
• status.
• default region or domain policy.
• resource limits.

3. Tenant Types

Tenant types:

• personal: a personal workspace.
• team: a small team workspace.
• enterprise: an enterprise team workspace.
• private: private deployment or self-hosted workspace.

Tenant remains the default isolation boundary for resources, API access, usage, quota, and desired state compilation.

4. Identity Model

User is a human or system principal.

Membership connects a user to a tenant:

membership:
  tenant_id
  user_id
  role
  status

The effective permission for normal business APIs is derived from active memberships.

Future identity integrations must map external identities into this model:

• OIDC user subject -> OrbitMesh user.
• OIDC groups -> tenant roles through group mapping.
• Feishu department or group -> tenant roles through group mapping.
• WeCom department or group -> tenant roles through group mapping.
• GitHub team -> tenant roles through group mapping.

Business use cases must not depend directly on an external identity provider. They consume CurrentUser, active memberships, roles, and future resolved permissions.

5. External Group Mapping

External group mapping is a future extension, but the model must reserve the concept now.

Target mapping:

IdentityProvider
  -> ExternalGroup
      -> Team or Tenant
      -> Role

Examples:

github:orbitmesh-official/owners -> tenant:production owner
github:orbitmesh-official/platform -> tenant:production admin
feishu:network-team -> tenant:production admin
wecom:ops-viewers -> tenant:production viewer
oidc:group:contractors -> tenant:staging member

Mapping rules:

• External identity only produces effective membership or permission.
• Tenant data queries still filter by tenant_id.
• Business services do not call Feishu, WeCom, GitHub, or OIDC APIs directly.
• A user can belong to multiple tenants through direct membership and external group mapping.

6. Role Baseline

Target tenant roles:

• owner
• admin
• member
• viewer

Current compatibility role:

• operator

operator is treated as admin-equivalent while existing data and tests still use it. New product design should prefer admin.

Role intent:

7. Permission Baseline

Tenant-wide readers:

• owner.
• admin.
• viewer.
• operator.

Tenant managers:

• owner.
• admin.
• operator.

Own-resource creators:

• owner.
• admin.
• member.
• operator.

Baseline permissions:

member must not read or mutate another user's client access subscriptions.

viewer can read tenant-wide state but cannot mutate resources.

8. Client Access Subscription Ownership

Client access subscriptions are per-user credentials.

Rules:

• Every client access subscription has tenant_id and user_id.
• A member can create subscriptions only inside tenants where they have an active membership.
• A member can list, update, rotate, revoke, and delete only their own subscriptions.
• Admin-like roles can manage all subscriptions in the tenant.
• Viewer can read tenant-wide subscriptions but cannot mutate them.
• Subscription credentials must stay isolated per subscription.
• Rotating one subscription must not rotate credentials for another subscription.
• Revoking or deleting one subscription must trigger desired state recompilation for affected entry runtimes.

This keeps shared tenant entry nodes usable while preserving per-user access control and quota attribution.

9. Resource Ownership

Tenant-owned resources:

• Node.
• Capability Binding.
• Runtime Binding.
• Endpoint.
• Domain.
• Certificate.
• Deployment Token.
• Traffic Policy.
• Quota Policy.
• Desired State.
• Health Check.
• Metrics.
• Usage Rollup.
• Audit Event.

User-owned resources inside a tenant:

• Client Access Subscription.
• Subscription protocol credentials.
• Future personal access tokens.
• Future personal client devices.

Node ownership types:

• byoh: user or tenant brings the host.
• managed: platform-managed dedicated node.
• shared: platform-managed node authorized for multiple tenants.

Shared resources must enforce:

• tenant authorization.
• subscription credential isolation.
• traffic and quota attribution.
• endpoint authorization.
• desired state isolation.

10. API Requirements

Every authenticated request resolves:

• user.
• active memberships.
• tenant context when required.
• role or effective permission.

Business APIs must:

• reject unauthenticated requests.
• check active membership before tenant access.
• apply tenant_id filters to tenant-scoped queries.
• apply user_id filters for member-owned subscription lists.
• return 403 for tenant access violations.
• return 404 for resources hidden by authorization when appropriate.

The frontend may route by tenant in the future, for example:

/:tenant_id/nodes
/:tenant_id/subscriptions
/:tenant_id/settings/members

The current console can keep an implicit active tenant while the API model remains tenant-aware.

11. Database Requirements

All tenant-scoped tables must include tenant_id.

User-owned tenant resources must include both:

• tenant_id
• user_id

Current baseline tables:

users
tenants
memberships
subscriptions
subscription_protocol_credentials

Future identity and team tables:

teams
team_memberships
identity_providers
external_identities
external_groups
external_group_mappings
role_definitions
permission_definitions
role_permission_bindings

Custom roles are deferred. Built-in roles are enough for the current baseline.

12. Console Administration

Console should be organized around team and tenant operations:

• Overview.
• Nodes.
• Traffic.
• Client Access Subscriptions.
• Routing Policies.
• Usage and Quotas.
• Domains and TLS.
• Runtime Catalog.
• Deployment Tokens.
• Settings.

Settings should eventually include:

• Team.
• Members.
• Roles.
• Identity Providers.
• External Group Mappings.
• Tenant Plan.
• Audit.

For the current baseline, member management and identity provider management can remain planned, but the subscription pages must already respect per-user ownership.

13. Acceptance Criteria

Baseline acceptance:

• A user can belong to multiple tenants.
• A member can create a client access subscription in their tenant.
• A member lists only their own client access subscriptions.
• A member cannot rotate, revoke, update, or delete another user's subscription.
• An admin can manage all subscriptions in the tenant.
• A viewer can read tenant-wide subscriptions but cannot mutate them.
• Tenant-scoped SQL queries include tenant_id.
• Subscription list queries can filter by user_id.

Future acceptance:

• OIDC users can be mapped into OrbitMesh users.
• OIDC groups can map to tenant roles.
• Feishu and WeCom groups can map to tenant roles.
• GitHub Teams can map to tenant roles.
• Team can contain multiple tenants or workspaces.
• Custom roles can be added without changing business use cases.