Changeset 0.28.0.1 (#173)

docs/ICD/teams.md

@@ -0,0 +1,177 @@
+# Teams & Access Control
+
+### My Teams
+
+```
+GET /teams/mine                     → { "teams": [...] }
+```
+
+Returns teams the current user is a member of.
+
+### Team Administration
+
+Team-admin-scoped routes (require `RequireTeamAdmin` middleware):
+
+**Team CRUD (platform admin):**
+
+```
+GET    /admin/teams                  → { "teams": [...] }
+POST   /admin/teams
+GET    /admin/teams/:id
+PUT    /admin/teams/:id
+DELETE /admin/teams/:id
+```
+
+**Members:**
+
+```
+GET    /admin/teams/:id/members      → { "members": [...] }
+POST   /admin/teams/:id/members      ← { "user_id", "role" }
+PUT    /admin/teams/:id/members/:memberId  ← { "role" }
+DELETE /admin/teams/:id/members/:memberId
+```
+
+**Team-scoped routes** (team admin, not platform admin):
+
+```
+GET    /teams/:teamId/members
+POST   /teams/:teamId/members        ← { "user_id", "role" }
+PUT    /teams/:teamId/members/:memberId
+DELETE /teams/:teamId/members/:memberId
+```
+
+**Team Providers:**
+
+```
+GET    /teams/:teamId/providers      → { "configs": [...] }
+POST   /teams/:teamId/providers      ← { "name", "provider", "endpoint", "api_key", ... }
+PUT    /teams/:teamId/providers/:id
+DELETE /teams/:teamId/providers/:id
+GET    /teams/:teamId/providers/:id/models  → { "models": [...] }
+```
+
+**Team Models:**
+
+```
+GET /teams/:teamId/models           → { "models": [...] }
+```
+
+Available models for this team (global + team-scoped).
+
+**Team Personas:** See §4.2.
+
+**Team Roles:**
+
+```
+GET    /teams/:teamId/roles          → { "roles": [...] }
+PUT    /teams/:teamId/roles/:role    ← { "permissions": {...} }
+DELETE /teams/:teamId/roles/:role
+```
+
+**Team Audit:**
+
+```
+GET /teams/:teamId/audit             → paginated audit log
+GET /teams/:teamId/audit/actions     → { "actions": [...] } (distinct action types)
+```
+
+**Team Usage:**
+
+```
+GET /teams/:teamId/usage             → { "totals": {...}, "results": [...] }
+```
+
+### Groups & Resource Grants
+
+Groups are ACL containers that decouple access from team membership.
+A resource grant controls who can see a Persona or KB beyond its base
+scope.
+
+**My Groups:**
+
+```
+GET /groups/mine                     → { "groups": [...] }
+```
+
+**Admin Group CRUD:**
+
+```
+GET    /admin/groups                 → { "groups": [...] }
+POST   /admin/groups                 ← { "name", "scope", "team_id" }
+GET    /admin/groups/:id
+PUT    /admin/groups/:id
+DELETE /admin/groups/:id
+```
+
+**Group Members:**
+
+```
+GET    /admin/groups/:id/members     → { "members": [...] }
+POST   /admin/groups/:id/members     ← { "user_id" }
+DELETE /admin/groups/:id/members/:userId
+```
+
+**Resource Grants:**
+
+```
+GET /admin/grants/:type/:id          → { "grant": {...} }
+PUT /admin/grants/:type/:id          ← { "grant_type": "team_only|global|groups", "group_ids": [...] }
+DELETE /admin/grants/:type/:id
+```
+
+`:type` is `persona` or `kb`. `:id` is the resource ID.
+
+Grant types:
+
+| `grant_type` | Visibility |
+|--------------|-----------|
+| `team_only` | Only the owning team |
+| `global` | All authenticated users |
+| `groups` | Members of specified groups |
+
+### Permissions
+
+Groups carry fine-grained permissions. Permission resolution:
+union of all group permissions + Everyone group permissions.
+
+**List all permissions:**
+
+```
+GET /admin/permissions               → { "permissions": ["model.use", "kb.read", ...] }
+```
+
+**Get user's effective permissions:**
+
+```
+GET /admin/users/:id/permissions     → { "permissions": [...], "groups": [...] }
+```
+
+Returns the resolved permission set and contributing groups.
+
+**Group permission fields** (set via `PUT /admin/groups/:id`):
+
+```json
+{
+  "permissions": ["model.use", "kb.read", "channel.create"],
+  "token_budget_daily": 100000,
+  "token_budget_monthly": 3000000,
+  "allowed_models": ["claude-sonnet-4-20250514", "gpt-4o"]
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `permissions` | string[] | Permission constants granted to members |
+| `token_budget_daily` | int/null | Daily token ceiling (NULL = unlimited) |
+| `token_budget_monthly` | int/null | Monthly token ceiling (NULL = unlimited) |
+| `allowed_models` | string[]/null | Model allowlist (NULL = unrestricted) |
+
+**Everyone group:** System-seeded group (ID `00000000-0000-0000-0000-000000000001`)
+whose permissions apply to all authenticated users implicitly (no membership
+row needed). Editable by admins, cannot be deleted (`source=system`).
+
+**RequirePermission middleware:** Routes gated by permission check user's
+resolved permission set. Returns 403 if the required permission is not present.
+
+See [enums.md](enums.md) for the full permission constant list.
+