first commit
This commit is contained in:
npc0-hue
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-07-06
|
||||
@@ -0,0 +1,49 @@
|
||||
## Context
|
||||
|
||||
The platform already has session APIs, role-aware frontend navigation, and server lifecycle workflows. Server instances are currently global resources with no owner or administrator membership metadata, so frontend filtering alone cannot satisfy the required visibility and management rules.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Bootstrap the first public registration as an active platform administrator.
|
||||
- Persist server ownership and server administrator membership on each server instance.
|
||||
- Enforce server visibility and lifecycle authorization in platform APIs.
|
||||
- Let server owners invite and remove server administrators for their own servers while hiding platform administrators from owner-facing candidate lists.
|
||||
- Keep platform administrators able to view and manage all servers.
|
||||
|
||||
**Non-Goals:**
|
||||
- Add billing, cloud host sales, marketplace SaaS workflows, or external identity providers.
|
||||
- Add persistent database migrations beyond the current in-memory model.
|
||||
- Expose run credentials, raw host paths, AI provider keys, or plugin-side direct server management.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Store ACLs on server instances
|
||||
|
||||
Server instances will carry `OwnerUserID` and `AdminUserIDs` fields. This keeps authorization close to the managed resource and avoids adding a separate repository before the platform has persistent storage.
|
||||
|
||||
Alternative considered: add a dedicated membership repository. This was rejected for the current in-memory platform because it increases joins and lifecycle coordination without adding durability.
|
||||
|
||||
### Authorize at API/service boundaries
|
||||
|
||||
Handlers will require a bearer session for user-facing server APIs and call service methods that evaluate the current user before returning data or dispatching lifecycle jobs. Platform administrators bypass the per-server ACL; server owners and server administrators require membership.
|
||||
|
||||
Alternative considered: filter only in `platform_web`. This was rejected because direct API calls would still leak global server data.
|
||||
|
||||
### Bootstrap first registration by existing user count
|
||||
|
||||
Registration will inspect the user repository. If no users exist, the registered user becomes active with `platform-admin` and receives a session. Later registrations remain pending with `server-admin`.
|
||||
|
||||
Alternative considered: keep only a seeded local admin. This was rejected because production-like setup needs a first-account bootstrap path.
|
||||
|
||||
### Owner-managed administrator invitations use existing users
|
||||
|
||||
Server owner invitations will accept an existing active non-platform-admin user ID and add that user to the server administrator list. Removing an administrator deletes only the server membership, not the user account or platform role.
|
||||
|
||||
Alternative considered: invite by email and create accounts inline. This was rejected because the current user lifecycle already separates registration/approval from server membership assignment.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Risk] In-memory ACL state is not durable across process restart. -> Mitigation: keep this scoped to the existing in-memory platform and model fields so future persistence can mirror the contract.
|
||||
- [Risk] Existing tests that create server instances without auth may fail. -> Mitigation: keep service-level direct create helpers usable while requiring auth in HTTP handlers.
|
||||
- [Risk] Platform administrators accidentally appear as removable server admins. -> Mitigation: filter platform-admin users from owner-facing candidate/member responses and reject platform-admin membership mutations.
|
||||
@@ -0,0 +1,25 @@
|
||||
## Why
|
||||
|
||||
The current login and server management flow authenticates users but does not enforce the product rule that platform administrators can manage every server while server owners and server administrators only see their assigned servers. The platform also needs bootstrap-safe registration so the first real account becomes the platform administrator and later registrations remain server-scoped until invited or approved.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Make the first registered account an active platform administrator with an authenticated session.
|
||||
- Keep subsequent self-registrations server-scoped and pending until a platform administrator activates them.
|
||||
- Add owner and administrator membership fields to server instances and expose them in bounded API responses.
|
||||
- Scope server list/detail/lifecycle APIs by current user: platform administrators see all servers; owners and administrators see only owned or managed servers.
|
||||
- Add server owner APIs to invite and remove server administrators without exposing platform administrators as invite candidates.
|
||||
- Add frontend contracts, client methods, server detail UI, and tests for owner-managed administrator membership.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `role-scoped-server-access`: Registration bootstrap, server ownership, server administrator membership, and role-scoped server visibility/actions.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
## Impact
|
||||
|
||||
- Affects `platform/` domain, DTOs, validation, repository filters, service authorization helpers, API handlers, route docs, and tests.
|
||||
- Affects `platform_web/` API types/client methods, server list/detail pages, user/admin display logic, and tests.
|
||||
- Preserves existing platform/run/plugin boundaries; no raw credentials, host paths, direct sockets, or AI provider keys are exposed to plugins or the frontend.
|
||||
+72
@@ -0,0 +1,72 @@
|
||||
## 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.
|
||||
@@ -0,0 +1,19 @@
|
||||
## 1. Backend Model And Authorization
|
||||
|
||||
- [x] 1.1 Add server owner/admin membership fields, DTOs, copy helpers, filters, and validators.
|
||||
- [x] 1.2 Update registration bootstrap so the first user becomes an authenticated platform administrator.
|
||||
- [x] 1.3 Add service authorization helpers for platform admin, server owner, and server administrator visibility.
|
||||
- [x] 1.4 Scope server list/detail/lifecycle HTTP APIs by bearer session and server ACLs.
|
||||
- [x] 1.5 Add owner APIs for listing invite candidates, inviting administrators, and removing administrators.
|
||||
|
||||
## 2. Frontend User Flow
|
||||
|
||||
- [x] 2.1 Add API types and client methods for server membership and invite candidates.
|
||||
- [x] 2.2 Render owner/admin metadata and owner-only administrator management in server detail.
|
||||
- [x] 2.3 Ensure server-only users continue landing on and seeing only their server list/detail workspaces.
|
||||
|
||||
## 3. Verification
|
||||
|
||||
- [x] 3.1 Add backend tests for bootstrap registration, server ACL visibility, lifecycle authorization, and owner membership changes.
|
||||
- [x] 3.2 Add frontend tests for role-scoped server UI and membership client behavior.
|
||||
- [x] 3.3 Run OpenSpec strict validation, structure checks, backend tests, frontend tests, and browser walkthrough.
|
||||
Reference in New Issue
Block a user