Module admin 

The admin HTTP API (Phase 12, increment 1).

A REST surface, mounted under /admin, that the Next.js management console (increment 2) consumes: whoami, chat history, indexing status, and document sets. Everything except /admin/health is gated by [require_role] and org-scoped to the caller’s Principal.

Routes + role gates

route	min role	scope
GET /admin/health	— (public)	liveness only
GET /admin/me	Basic	the caller’s own principal
GET /admin/conversations	Basic	Admin/Curator: org-wide; Basic: own only
GET /admin/conversations/{id}/messages	Basic	role-scoped (Basic must own the convo)
GET /admin/indexing/runs	Curator	org connectors
GET /admin/document-sets	Curator	org document sets

Org-scoping + “Basic sees own”

Every read filters to principal.org_id (the storage adapter’s list_conversations_by_org). For a Basic caller, the result is further narrowed to conversations the caller owns: a conversation is owned when one of its User participants carries external_id == principal.user_id. An Admin or Curator sees the whole org. This mirrors the document-level AccessContext model RBAC sits on top of.

Errors

Auth failures map to clean status codes (401 unauthenticated / invalid token / missing role; 403 insufficient role) with the protocol’s error envelope shape ({ code, message }) reused for the body. Never leaks a token.

Structs

AuthRejection

An auth/authorization rejection rendered as the protocol’s error envelope with the right HTTP status.

RequireRole

An authenticated Principal guaranteed to hold at least role MIN.

Functions

router

Build the /admin router over the shared AppState.