feat(auth): add sessionCanManageApiKeys function and update access control logic

Introduced the sessionCanManageApiKeys function to determine if a session can manage API keys based on role, permissions, and admin status. Updated the AccessComponent to utilize this new function for enabling/disabling API key management features. Enhanced documentation to reflect changes in API key management roles and permissions, including updates to the OpenAPI specification.

apps/web/src/lib/auth.ts

@@ -259,6 +259,30 @@ export function can(required: string): boolean {
   return hasPermission(claims.permissions, required)
 }
 
+/**
+ * Whether /v1/auth/session may manage API keys (`bgp:access:admin`).
+ * Mirrors backend `requirePerm` for JWT (is_admin / permissions) and API-key operator.
+ */
+export function sessionCanManageApiKeys(session: {
+  role?: string
+  kind?: string
+  is_admin?: boolean
+  permissions?: readonly string[]
+} | null | undefined): boolean {
+  if (!session) return false
+  const jwtPath =
+    session.kind === 'jwt' ||
+    session.is_admin === true ||
+    (session.permissions?.length ?? 0) > 0
+  if (jwtPath) {
+    return (
+      session.is_admin === true ||
+      hasPermission(session.permissions ?? [], 'bgp:access:admin')
+    )
+  }
+  return session.role === 'operator'
+}
+
 /** Nav path → minimum permission to show the item. Sync with app-shell NAV. */
 export function permissionForPath(pathname: string): string | null {
   if (pathname === '/' || pathname.startsWith('/dashboard')) {