// Generated from types/*.ts — do not edit.
// Regenerate with: npm run generate:typescript

/**
 * Common Notification Types — `auth/required`, currently the only connection-
 * level (non-channel-specific) protocol notification.
 *
 * @module common/notifications
 */

import type { ProtectedResourceMetadata, URI } from './state.js';

/**
 * Reason why authentication is required.
 *
 * @category Protocol Notifications
 * @nonexhaustive
 */
export const enum AuthRequiredReason {
  /** The client has not yet authenticated for the resource */
  Required = 'required',
  /** A previously valid token has expired or been revoked */
  Expired = 'expired',
}

// ─── auth/required ───────────────────────────────────────────────────────────

/**
 * Sent by the server when a protected resource requires (re-)authentication.
 *
 * This notification MAY be associated with any channel — for example, an
 * agent advertised on the root channel, or a per-session resource. The
 * `channel` field identifies the subscription the auth requirement belongs
 * to; the `resource` field carries the complete OAuth protected resource
 * metadata (per RFC 9728).
 *
 * Clients should obtain a fresh token and push it via the `authenticate`
 * command.
 *
 * @category Protocol Notifications
 * @method auth/required
 * @direction Server → Client
 * @messageType Notification
 * @version 1
 * @see {@link /specification/authentication | Authentication}
 * @example
 * ```json
 * {
 *   "jsonrpc": "2.0",
 *   "method": "auth/required",
 *   "params": {
 *     "channel": "ahp-root://",
 *     "resource": {
 *       "resource": "https://api.github.com",
 *       "resource_name": "GitHub API",
 *       "authorization_servers": ["https://github.com/login/oauth"]
 *     },
 *     "reason": "expired"
 *   }
 * }
 * ```
 */
export interface AuthRequiredParams {
  /** Channel URI this notification belongs to */
  channel: URI;
  /** Complete RFC 9728 metadata for the protected resource that requires authentication */
  resource: ProtectedResourceMetadata;
  /** Why authentication is required */
  reason?: AuthRequiredReason;
}