Scoped operator tokens, one-time enrollment, and scoped profile contracts (milestone 0)

[XelHaku]

Draft — not requesting review/merge yet. Opening for visibility and discussion of the contract. One validation step (on-device enrollment + accessibility receipt) is still outstanding; see caveats below.

What this adds

A scoped-operator-token trust foundation for the API server, so a mobile client can be granted least-privilege, revocable access without sharing the superuser API_SERVER_KEY. This is milestone 0 ("Remote trust foundation") of a Flutter client's parity effort; it is purely additive — the existing API_SERVER_KEY path is unchanged and continues to authenticate as superuser (*).

New surface (all under gateway/)

• api_operator_auth.py — scope vocabulary (normalize_scopes, AuthPrincipal), and a hashed, revocable OperatorCredentialStore (SHA-256 of a 256-bit token, hmac.compare_digest, one-time raw return, 0600 atomic writes, per-record fail-closed loading).
• api_operator_enrollment.py — one-time, origin-bound, TTL-limited pairing-code enrollment that mints scoped tokens (salted-hash code storage, single-use atomic consume, lockout).
• api_server.py — _authorize(request, required_scope): constant-time API_SERVER_KEY → superuser, else operator-token → scoped principal, else 401; insufficient_scope 403 never echoes granted scopes. Every mutating route is :write-gated. /v1/capabilities now advertises schema_version, an auth block, and per-endpoint required_scopes / profile_scoped. Adds scoped profile CRUD + soul contracts (profiles:read/write) with If-Match optimistic concurrency (428 missing, 412 stale-no-write) that reuse the existing hermes_cli.profiles domain functions — no Dashboard proxy, no active_profile mutation, no shell-wrapper creation for remote clients.

Evidence

• 257 gateway tests pass on the merged tree (the pre-existing Telegram/Wecom failures are unrelated and unchanged).
• tests/gateway/test_milestone0_receipt.py drives the real handlers end-to-end: mint → inspect → single-use exchange → scoped profile create/list/soul/rename/delete with If-Match → revoke → revoked token 401 (fail closed).
• Each piece was security-reviewed; fixes in-branch cover wildcard scope validation, per-record fail-closed credential loading, path-free error bodies, and suppressing remote-rename wrapper creation.

Caveats / not-yet-done

• On-device receipt pending: a real phone enrolling against a running instance (and the client-side accessibility pass) has not yet been captured, so the client parity rows remain implementing, not validated.
• /api/cron/fire keeps its purpose-built NAS-JWT auth (an audited exception to the operator-scope gating).
• Operator enrollment uses a store-global lockout (single-owner-install assumption); expired/consumed rows are not pruned.

Happy to split this into smaller PRs (vocabulary/store → authorization → enrollment → profiles) if that's easier to review.

🤖 Generated with Claude Code

[tonydwb]

Code Review Summary

Verdict: Comment (High Surface Area)

Overview

Milestone 0 for scoped operator tokens: one-time enrollment and scoped profile contracts. 2815 additions, 151KB diff, multiple files.

Assessment

• Scope: Large feature PR touching auth/token enrollment — high security sensitivity.
• Security: Token enrollment logic requires careful review for token scope boundaries, expiration, and enrollment uniqueness.
• Debug artifacts: 8 debug hits; verify no leftover logging in token handling paths.
• Secret scan: 42 hits — verify all are test fixtures/variable names, not real credentials.

Recommendation

Human deep-dive review recommended for token scope enforcement and one-time enrollment uniqueness before merge.

---

Reviewed by Hermes Agent

[teknium1]

Thanks for the detailed scope model and lifecycle tests. The feature is not present on current main, but the current API-server path has moved and this needs conflict-aware salvage.

Problems

• Current main's admission wrapper still calls legacy _check_auth before decorated agent handlers (gateway/platforms/api_server.py:687). The PR moves scope checks into handlers such as gateway/platforms/api_server.py:2551; preserve admission/drain behavior while allowing a valid scoped token to reach those checks, and test actual scoped chat/session/runs requests.
• Browser profile mutations cannot preflight: _CORS_HEADERS omits PATCH, PUT, and If-Match (gateway/platforms/api_server.py:562), while the PR adds the PATCH and PUT profile routes (gateway/platforms/api_server.py:5303-5306).
• rename_profile(..., no_alias=True) skips removing an existing old wrapper as well as creating a new one (gateway/platforms/api_server.py:2406; hermes_cli/profiles.py:1971). The new test covers only a wrapper-free setup.

Suggested changes

• Preserve the current admission wrapper and make it scope-aware; add endpoint-level scoped-token coverage.
• Extend CORS methods/headers and add a preflight regression test.
• Remove stale old aliases without creating a new remote alias.

Automated hermes-sweeper review.

[teknium1]

When this is salvaged onto current main, the current @_admit_api_agent_request wrapper still calls legacy _check_auth before this handler and will reject a valid scoped bearer token before _authorize runs. Preserve the admission/drain accounting but make its authentication accept scoped principals; add an endpoint test that reaches this path with a chat:write token.

[teknium1]

These profile mutations require If-Match, but _CORS_HEADERS still allows only GET/POST/DELETE and omits If-Match. A browser at an allowed CORS origin cannot preflight this PUT (or the PATCH route above). Add PATCH, PUT, and If-Match plus an OPTIONS regression test.

[teknium1]

no_alias=True also skips remove_wrapper_script(old_canon), leaving a stale old-name wrapper for profiles originally created through the CLI. Split suppressing new-wrapper creation from cleanup of an existing old wrapper, and test a rename that starts with one.