browser/openspec/changes/implement-role-scoped-server-access/specs/role-scoped-server-access/spec.md

ADDED Requirements

Requirement: First registration bootstraps platform administration

The platform SHALL make the first registered user an active platform administrator and return an authenticated session for that registration.

Scenario: First registered user becomes platform administrator

• WHEN there are no existing users and a valid registration request is submitted
• THEN the created user has status active, includes the platform-admin role, and receives a session token.

Scenario: Later registered users remain server scoped

• WHEN at least one user exists and a valid registration request is submitted
• THEN the created user has status pending, includes only the server-admin role by default, and does not receive platform administrator privileges.

Requirement: Server instances carry owner and administrator membership

Server instances SHALL persist one owner user ID and zero or more server administrator user IDs.

Scenario: Server is created by an authenticated server owner

• WHEN an authenticated non-platform user creates a server workflow
• THEN the created server records that user as ownerUserId and returns the owner in the server response.

Scenario: Server membership is bounded in responses

• WHEN a server instance is returned by list, detail, or lifecycle APIs
• THEN the response includes ownerUserId and adminUserIds without exposing credentials or platform administrator-only data.

Requirement: Server visibility is role scoped

The platform SHALL scope user-facing server APIs by the authenticated user.

Scenario: Platform administrator lists servers

• WHEN a platform administrator lists server instances
• THEN all non-filtered matching server instances are returned.

Scenario: Server owner lists servers

• WHEN a server owner lists server instances
• THEN only servers where the user is the owner or a server administrator are returned.

Scenario: Server administrator opens unmanaged server

• WHEN a server administrator requests a server they do not own or administer
• THEN the request is rejected with forbidden or not found semantics and no server details are returned.

Requirement: Server owners manage server administrators

The platform SHALL let a server owner invite and remove server administrators for servers they own.

Scenario: Owner invites server administrator

• WHEN a server owner invites an active non-platform-admin user to administer their server
• THEN that user is added to the server adminUserIds list and can see/manage that server.

Scenario: Owner removes server administrator

• WHEN a server owner removes an existing server administrator from their server
• THEN that user is removed from the server adminUserIds list and can no longer see that server unless they own it or have platform administrator privileges.

Scenario: Owner cannot manage platform administrators

• WHEN a server owner lists invite candidates or attempts to add/remove a platform administrator
• THEN platform administrators are hidden from owner-facing membership lists and membership mutation is rejected.

Scenario: Non-owner cannot change membership

• WHEN a server administrator attempts to invite or remove administrators for a server they do not own
• THEN the request is rejected.

Requirement: Frontend exposes owner-scoped administrator management

The frontend SHALL show server administrator management controls only where the current user can use them.

Scenario: Owner sees member controls

• WHEN a server owner opens a server they own
• THEN the server detail page shows current server administrators and invitation/removal controls.

Scenario: Server administrator sees no owner controls

• WHEN a server administrator opens a server they administer but do not own
• THEN the page hides invitation/removal controls while keeping allowed server operations visible.

Scenario: Platform administrator can inspect all servers

• WHEN a platform administrator opens any server
• THEN the page remains accessible and avoids presenting owner-only membership controls as if the platform administrator were removable.