Proposal: Agent-native Admin API (scoped mnfst_admin_ai_* key) for self-hosted management

[sponsorrockit1]

Summary

Self-hosted Manifest instances today are managed almost entirely through the
dashboard (browser session / owner API key). There is no stable, key-authenticated
machine surface for programmatically administering agents, attaching provider
keys, and reading routing/usage — the exact thing an AI agent or ops automation
needs to onboard and operate harnesses (OpenClaw, Hermes, etc.) without a human
in the browser.

I'd like to propose adding a scoped AI-admin API under /api/v1/admin,
gated by a new key scope (ai_admin) carried on a dedicated key prefix
mnfst_admin_ai_*. This is a thin, additive layer over the existing NestJS
service layer (agents, providers, routing, timeseries) — no new business logic,
no new infrastructure.

Why a new scope instead of reusing owner keys

Owner keys (api_keys rows with scope='owner', prefix mnfst_*) resolve to the
tenant but are also accepted by the dashboard's owner-only endpoints. An AI-admin
key should be narrowly scoped so it can administer agents/providers/observability
but cannot, by construction, hit owner-only account/session endpoints. The guard
enforces this: AdminAiGuard rejects owner keys with 403 and unknown keys with 401.

Design (additive, no breaking changes)

• New scope column on api_keys (default owner). Migration included.
• New key_hash column on tenant_providers (so provider keys can be
  match-verified without ever returning the raw secret). Migration included.
• ApiKeyGuard stashes the resolved scope on the request; AdminAiGuard
  authorizes /api/v1/admin/* to ai_admin only.
• Endpoints (all return 401 without key, 403 with owner key):
  • GET/POST/DELETE /api/v1/admin/keys — mint/list/revoke admin keys (raw key returned exactly once at mint).
  • GET/POST/PATCH/DELETE /api/v1/admin/agents[/:name] — full agent CRUD + rotate-key + duplicate (reuses AgentLifecycleService etc.).
  • GET/POST /api/v1/admin/providers[/:provider/keys] — list + attach/update provider key.
  • POST /api/v1/admin/providers/:provider/keys/verify — match-verify: you POST the key, it returns { match: boolean }. The raw secret is never returned (addresses the "can I confirm a key is correct without exposing it" problem for BYOK).
  • GET /api/v1/admin/observability/* — read-only usage + per-agent routing.

Security properties

• No handler returns a stored provider/agent secret; ingest keys are returned only at creation/rotation/duplicate (same as the dashboard).
• Provider key verification is salt-aware (verifyKey), never a raw compare.
• Migrations are additive with defaults; existing rows untouched.

Status

Implemented on a fork branch feat/agent-admin-api, built into a local image,
deployed to a live self-hosted instance, and exercised end-to-end (agent
CRUD, key rotate/duplicate, provider attach + match-verify both directions,
observability, scope enforcement 401/403). Build green, existing
custom-provider + provider-key specs still pass (22/22). A changeset is included.

Questions for maintainers

1. Is a dedicated ai_admin scope the preferred modeling, or would you rather see this expressed as a permission bitmask on the existing key?
2. Provider key match-verify — useful as a first-class endpoint, or should it be folded into the existing provider update response?
3. Naming: mnfst_admin_ai_* prefix — acceptable, or prefer something else?

I've opened a corresponding PR from sponsorrockit1:feat/agent-admin-api so the
implementation can be reviewed alongside this proposal. Happy to adjust the
scope/shape to match project conventions before merge.