docs: sprint 2 surface in docs/api.md + D-015/D-016/D-017 + changelog
- `docs/api.md` extended with the sprint-2 surface: pagination envelope
conventions, engagement members (GET/POST/DELETE), users (GET paginated
with `?type=`, POST, PATCH, DELETE-soft), audit log viewer with its
five filters. Anti-enumeration semantics (404 on foreign members) made
explicit. Drive-by fix: `/engagements<eid>` → `/engagements/<eid>`.
- `tasks/spec-decisions.md` logs the three sprint-2 decisions verbatim:
- **D-015** USER_MANAGE permission (wording from spec-analyst).
- **D-016** pagination envelope shape (`{items, total, page, page_size}`).
- **D-017** `engagement_member.role` stays a free-form label.
- `CHANGELOG.md` summarises the sprint with hashes / behaviours / decisions.
This commit is contained in:
knacky
181
docs/api.md
181
docs/api.md
@@ -1,6 +1,7 @@
|
||||
# Mimic API — sprint 1 surface
|
||||
# Mimic API — sprint 1 + 2 surface
|
||||
|
||||
This document covers the endpoints the frontend is expected to call in sprint 1.
|
||||
This document covers the endpoints the frontend is expected to call in
|
||||
sprints 1 and 2 (auth, engagements, users, engagement members, audit log).
|
||||
Everything is JSON, every protected route relies on the Flask session cookie set
|
||||
by `POST /api/v1/auth/login`. CORS is enabled only when `MIMIC_ENV=development`
|
||||
and `MIMIC_CORS_ORIGINS` is set (the prod reverse proxy serves the SPA on the
|
||||
@@ -68,6 +69,19 @@ RT operators only see engagements they are members of. Requests targeting an
|
||||
engagement they don't belong to return **404**, never 403, so the existence of a
|
||||
neighbouring engagement is not leaked between teams. RT leads see everything.
|
||||
|
||||
This applies to every `/api/v1/engagements/<eid>/...` route, including the
|
||||
`/members` sub-resource introduced in sprint 2.
|
||||
|
||||
### Pagination (D-016)
|
||||
|
||||
The new sprint-2 endpoints (`/users`, `/audit/log`) return:
|
||||
```json
|
||||
{ "items": [...], "total": <n>, "page": 1, "page_size": 50 }
|
||||
```
|
||||
Query: `?page=` (≥1, default 1) and `?page_size=` (default 50, max 200). The
|
||||
existing non-paginated endpoints (`/engagements` list, `/engagements/<id>/members`)
|
||||
stay as flat arrays — they'll migrate together in a future opt-in.
|
||||
|
||||
## Authentication
|
||||
|
||||
### `POST /api/v1/auth/login`
|
||||
@@ -148,7 +162,7 @@ Response — `200`:
|
||||
]
|
||||
```
|
||||
|
||||
### `GET /api/v1/engagements<eid>`
|
||||
### `GET /api/v1/engagements/<eid>`
|
||||
|
||||
Same payload shape as the list element. Returns 404 if the engagement does not
|
||||
exist or the caller is not a member (MA6).
|
||||
@@ -178,6 +192,167 @@ on creation; they see every engagement via the `is_rt_lead()` short-circuit.
|
||||
This will change in a future sprint when membership becomes the single scope
|
||||
authority.
|
||||
|
||||
## Engagement members (sprint 2)
|
||||
|
||||
The MA6 tenant-scope check (`_engagement_or_404`) runs **before** any
|
||||
membership query: a non-member RT operator targeting an engagement gets the
|
||||
same `404 not_found` as if the engagement did not exist.
|
||||
|
||||
### `GET /api/v1/engagements/<eid>/members`
|
||||
|
||||
Lists members of the engagement (`engagement.read`). Flat array, not paginated.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"engagement_id": "•••",
|
||||
"user_id": "•••",
|
||||
"role": "binôme A",
|
||||
"added_at": "2026-05-23T12:00:00+00:00"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### `POST /api/v1/engagements/<eid>/members`
|
||||
|
||||
Adds a member (`engagement.member.manage`).
|
||||
|
||||
```json
|
||||
{ "user_id": "•••", "role": "member" }
|
||||
```
|
||||
|
||||
- `role` is a free-form label ≤40 chars (D-017); not a permission gate.
|
||||
Defaults to `"member"`.
|
||||
- `201` with the new `EngagementMemberRead`.
|
||||
- `404` if the user does not exist or is disabled.
|
||||
- `409 already_member` if the user is already in this engagement.
|
||||
- Audit `engagement_member.add` row written.
|
||||
|
||||
### `DELETE /api/v1/engagements/<eid>/members/<uid>`
|
||||
|
||||
Revokes membership (`engagement.member.manage`).
|
||||
|
||||
- `204 No Content` on success.
|
||||
- `404` if the membership does not exist.
|
||||
- Audit `engagement_member.remove` row written.
|
||||
|
||||
## Users (sprint 2, `rt_lead` only — D-015)
|
||||
|
||||
All four routes require `USER_MANAGE`. `rt_operator` and `soc_analyst` get
|
||||
`403 forbidden`.
|
||||
|
||||
### `GET /api/v1/users`
|
||||
|
||||
Paginated. Optional filter `?type=rt_lead|rt_operator|soc_analyst`.
|
||||
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"id": "•••",
|
||||
"email": "alice@example.org",
|
||||
"display_name": "Alice",
|
||||
"type": "rt_lead",
|
||||
"disabled_at": null,
|
||||
"last_login_at": "2026-05-23T08:00:00+00:00",
|
||||
"created_at": "2026-05-21T10:00:00+00:00"
|
||||
}
|
||||
],
|
||||
"total": 1,
|
||||
"page": 1,
|
||||
"page_size": 50
|
||||
}
|
||||
```
|
||||
|
||||
### `POST /api/v1/users`
|
||||
|
||||
Body:
|
||||
```json
|
||||
{
|
||||
"email": "newuser@example.org",
|
||||
"display_name": "New User",
|
||||
"password": "longenough",
|
||||
"type": "rt_operator"
|
||||
}
|
||||
```
|
||||
|
||||
- `password` ≥ 8 chars, ≤ 128.
|
||||
- `type` ∈ `rt_operator | rt_lead | soc_analyst`. Group membership is wired
|
||||
automatically to the matching F11 group.
|
||||
- `201` with the created `UserRead`.
|
||||
- `409 email_taken` if a user with that email exists (whether active or
|
||||
already disabled).
|
||||
- Audit `user.create` row written.
|
||||
|
||||
### `PATCH /api/v1/users/<uid>`
|
||||
|
||||
Partial update — every field is optional.
|
||||
|
||||
```json
|
||||
{ "display_name": "Renamed", "type": "rt_lead", "password": "newlongenough" }
|
||||
```
|
||||
|
||||
- Changing `type` realigns the user's global F11 group membership; existing
|
||||
per-engagement memberships are preserved.
|
||||
- `password` rotates the bcrypt hash; never logged in audit metadata.
|
||||
- `200` with the updated `UserRead`.
|
||||
- `404` if the user does not exist.
|
||||
- Audit `user.update` row written (lists changed fields; flags
|
||||
`password_rotated`).
|
||||
|
||||
### `DELETE /api/v1/users/<uid>`
|
||||
|
||||
Soft-disable: sets `disabled_at = now()`. The user can no longer log in;
|
||||
`load_user` returns `None` so existing sessions become anonymous on next
|
||||
request.
|
||||
|
||||
- `204 No Content`. Idempotent: a second call on a disabled user also returns
|
||||
`204` (no audit row).
|
||||
- `404` if the user does not exist.
|
||||
- Audit `user.disable` row written.
|
||||
|
||||
## Audit log (sprint 2, `rt_lead` only — F11 `audit.read`)
|
||||
|
||||
### `GET /api/v1/audit/log`
|
||||
|
||||
Paginated, descending by `ts`. Filters:
|
||||
|
||||
| Query | Type | Meaning |
|
||||
|-------|------|---------|
|
||||
| `action` | string | exact match (`user.create`, `engagement.update`, …) |
|
||||
| `actor_id` | UUID | filter by acting user |
|
||||
| `resource_type` | string | exact match (`engagement`, `user`, …) |
|
||||
| `since` | ISO 8601 | rows with `ts >= since` |
|
||||
| `until` | ISO 8601 | rows with `ts <= until` |
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"id": "•••",
|
||||
"ts": "2026-05-23T12:00:00+00:00",
|
||||
"actor_id": "•••",
|
||||
"action": "engagement.create",
|
||||
"resource_type": "engagement",
|
||||
"resource_id": "•••",
|
||||
"metadata_json": { "client_name": "Acme" },
|
||||
"prev_hash": "•••",
|
||||
"row_hash": "•••",
|
||||
"source_ip": "127.0.0.1",
|
||||
"user_agent": "curl/8.5.0",
|
||||
"comment": null
|
||||
}
|
||||
],
|
||||
"total": 42,
|
||||
"page": 1,
|
||||
"page_size": 50
|
||||
}
|
||||
```
|
||||
|
||||
`prev_hash` / `row_hash` are exposed as-is to support future client-side
|
||||
chain verification (D-013).
|
||||
|
||||
## Worked example
|
||||
|
||||
1. Create a local admin from the CLI:
|
||||
|
||||
Reference in New Issue
Block a user