Add scoped permissions for API keys

[sjmiller609]

Summary

• Adds a lib/scopes package that defines permission scopes following the resource:action pattern (e.g., instance:read, image:write, build:delete)
• JWT tokens can now carry a permissions claim with an array of scope strings; tokens without this claim retain full access (backward compatible)
• Auth middleware (JwtAuth and OapiAuthenticationFunc) extracts the permissions claim and stores parsed scopes in the request context
• A new scope enforcement middleware rejects requests missing the required scope with 403 Forbidden
• The hypeman-token CLI gains -scopes (comma-separated scope list) and -list-scopes flags
• WebSocket endpoints (exec, cp) enforce instance:write scope via RequireScope

Scope mapping

All API routes are mapped to scopes in lib/scopes/scopes.go:routeScopes. The resource types are:

Scope prefix	Resources
instance:	instances, exec, cp, start/stop/standby/restore/fork
image:	images
volume:	volumes, attach/detach
snapshot:	snapshots, instance snapshots
build:	builds
device:	devices
ingress:	ingresses
resource:	health, resources

Each prefix supports read, write, and delete actions (except resource: which is read-only). The wildcard * grants all permissions.

Usage

# Full-access token (backward compatible, no permissions claim)
hypeman-token -user-id myuser -duration 8760h

# Read-only token for instances and images
hypeman-token -user-id myuser -scopes "instance:read,image:read"

# Token that can manage instances but not delete them
hypeman-token -user-id myuser -scopes "instance:read,instance:write"

# List available scopes
hypeman-token -list-scopes

Test plan

• go test ./lib/scopes/ — scope parsing, validation, context helpers, RequireScope middleware
• go test ./lib/middleware/ — legacy tokens get full access, scoped tokens have permissions in context, wildcard tokens work
• go vet clean on all changed packages
• Integration test with live API: create a scoped token, verify allowed endpoints succeed and denied endpoints return 403

🤖 Generated with Claude Code

---

Note

Medium Risk
Introduces new authorization checks across API routes based on JWT permissions claims; misconfigured scope mappings or claim parsing could unintentionally block access or over/under-authorize requests.

Overview
Adds scoped API-key permissions via a new lib/scopes package, including scope definitions (e.g. instance:read), a per-route scope map, and middleware that returns 403 Forbidden when a request lacks the required scope.

Updates JWT authentication (JwtAuth and OapiAuthenticationFunc) to extract an optional permissions claim into request context (missing claim remains full access for backward compatibility; malformed claim becomes deny all), wires scope enforcement into the main API router, and applies instance:write checks to the exec/cp WebSocket endpoints.

Extends the hypeman-token CLI to list available scopes and mint scoped tokens, and adds tests to ensure scope enforcement works and that all routes are mapped (or explicitly public).

^{Written by Cursor Bugbot for commit 1f3e39e. This will update automatically on new commits. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}