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

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

/**
 * Reason why authentication is required.
 *
 * @category Protocol Notifications
 */
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 OAuth-protected resource identifier
 * (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": "https://api.github.com",
 *     "reason": "expired"
 *   }
 * }
 * ```
 */
export interface AuthRequiredParams {
  /** Channel URI this notification belongs to */
  channel: URI;
  /** The protected resource identifier that requires authentication */
  resource: string;
  /** Why authentication is required */
  reason?: AuthRequiredReason;
}
