R/errors__constructors.R

Defines functions sanitize_body err_parse err_input err_config err_userinfo_mismatch err_userinfo err_id_token err_token err_oidc_nonce err_pkce err_invalid_state err_transport err_http normalize_bullets short_desc_for_class deprecate_warn_pkg inform_pkg warn_pkg abort_pkg format_condition_message format_header err_abort

# This file contains error-constructor helpers for shinyOAuth
# Used for creating package-specific errors with consistent messages, classes,
# trace ids, and structured context

# 1 Error constructors ---------------------------------------------------------

## 1.1 Generic constructors and formatting -------------------------------------

# Functions in this subsection create the base package condition and prepare
# the small formatting helpers it needs.

#' Abort with a typed shinyOAuth error
#'
#' Builds a typed shinyOAuth condition, emits the matching trace event, and
#' aborts with a resolved trace id. Used by all specialized `err_*()` wrappers.
#'
#' @param msg Error message or rlang-style bullet vector.
#' @param class Condition class or class vector to add to the error.
#' @param context Named list of structured context fields.
#' @param trace_id Optional trace id to reuse for the error.
#' @return No return value. This function always aborts.
#' @keywords internal
#' @noRd
err_abort <- function(
  msg,
  class = "shinyOAuth_error",
  context = list(),
  trace_id = NULL
) {
  trace_id <- resolve_trace_id(trace_id)
  emit_trace_event(c(
    list(type = "error", trace_id = trace_id, message = msg),
    context
  ))
  primary <- short_desc_for_class(c(class, "shinyOAuth_error"))
  message <- format_condition_message(
    primary,
    msg,
    footer = c("i" = paste0("Trace ID: ", trace_id))
  )
  rlang::abort(
    message = message,
    class = c(class, "shinyOAuth_error"),
    trace_id = trace_id,
    context = context
  )
}

#' Format the standard shinyOAuth condition header
#'
#' Used by errors, warnings, and informs that present a concise shinyOAuth
#' title line before their bullet details.
#'
#' @param short Short description shown in the condition header.
#' @param strong Whether to render `short` in bold via cli markup.
#' @return A formatted header string.
#' @keywords internal
#' @noRd
format_header <- function(short, strong = TRUE) {
  short <- as.character(short %||% "")

  if (isTRUE(strong)) {
    return(paste0("[{.pkg shinyOAuth}] - {.strong ", short, "}"))
  }

  paste0("[{.pkg shinyOAuth}] - ", short)
}

#' Build a standard shinyOAuth condition message
#'
#' Combines the package header, normalized bullet body, and any footer bullets
#' into the character vector expected by `rlang` condition helpers.
#'
#' @param short Short description shown in the condition header.
#' @param msg Condition body as a string, bullet vector, or one-level list.
#' @param default_type Bullet type assigned to unnamed body entries.
#' @param footer Optional footer bullets appended after the main body.
#' @param strong Whether to render `short` in bold via cli markup.
#' @return A named character vector suitable for `rlang::abort()`/
#'   `rlang::warn()`/`rlang::inform()`.
#' @keywords internal
#' @noRd
format_condition_message <- function(
  short,
  msg = NULL,
  default_type = "!",
  footer = NULL,
  strong = TRUE
) {
  c(
    format_header(short, strong = strong),
    normalize_bullets(msg, default_type = default_type),
    normalize_bullets(footer, default_type = "i")
  )
}

#' Abort with standard shinyOAuth formatting
#'
#' Used by package helpers that need a custom error title while keeping the same
#' header and bullet structure used by other shinyOAuth conditions.
#'
#' @param short Short description shown in the condition header.
#' @param msg Error body as a string, bullet vector, or one-level list.
#' @param ... Additional arguments forwarded to [rlang::abort()].
#' @param default_type Bullet type assigned to unnamed body entries.
#' @param footer Optional footer bullets appended after the main body.
#' @param strong Whether to render `short` in bold via cli markup.
#' @return No return value. This function always aborts.
#' @keywords internal
#' @noRd
abort_pkg <- function(
  short,
  msg = NULL,
  ...,
  default_type = "!",
  footer = NULL,
  strong = TRUE
) {
  rlang::abort(
    format_condition_message(
      short,
      msg,
      default_type = default_type,
      footer = footer,
      strong = strong
    ),
    ...
  )
}

#' Warn with standard shinyOAuth formatting
#'
#' Used by package helpers that emit advisory warnings with the same header and
#' bullet structure used by shinyOAuth errors.
#'
#' @param short Short description shown in the condition header.
#' @param msg Warning body as a string, bullet vector, or one-level list.
#' @param ... Additional arguments forwarded to [rlang::warn()].
#' @param default_type Bullet type assigned to unnamed body entries.
#' @param footer Optional footer bullets appended after the main body.
#' @param strong Whether to render `short` in bold via cli markup.
#' @return No meaningful return value; emits a warning side effect.
#' @keywords internal
#' @noRd
warn_pkg <- function(
  short,
  msg = NULL,
  ...,
  default_type = "!",
  footer = NULL,
  strong = TRUE
) {
  rlang::warn(
    format_condition_message(
      short,
      msg,
      default_type = default_type,
      footer = footer,
      strong = strong
    ),
    ...
  )
}

#' Inform with standard shinyOAuth formatting
#'
#' Used by package helpers that emit non-error operational notices while
#' keeping the same header structure as other shinyOAuth conditions.
#'
#' @param short Short description shown in the condition header.
#' @param msg Inform body as a string, bullet vector, or one-level list.
#' @param ... Additional arguments forwarded to [rlang::inform()].
#' @param default_type Bullet type assigned to unnamed body entries.
#' @param footer Optional footer bullets appended after the main body.
#' @param strong Whether to render `short` in bold via cli markup.
#' @return No meaningful return value; emits an inform side effect.
#' @keywords internal
#' @noRd
inform_pkg <- function(
  short,
  msg = NULL,
  ...,
  default_type = "i",
  footer = NULL,
  strong = TRUE
) {
  rlang::inform(
    format_condition_message(
      short,
      msg,
      default_type = default_type,
      footer = footer,
      strong = strong
    ),
    ...
  )
}

#' Warn about a deprecated shinyOAuth API with standard formatting
#'
#' Uses lifecycle's deprecation machinery to honor verbosity and once-per-id
#' behavior, then re-emits the warning with shinyOAuth's standard header.
#'
#' @param when Package version where the deprecation started.
#' @param what Deprecated API description.
#' @param with Optional replacement API description.
#' @param details Optional extra details as a string, bullet vector, or list.
#' @param id Optional lifecycle deprecation id.
#' @param env Environment forwarded to [lifecycle::deprecate_warn()].
#' @param user_env User environment forwarded to [lifecycle::deprecate_warn()].
#' @return No meaningful return value; emits a warning side effect when the
#'   deprecation is active under current lifecycle verbosity settings.
#' @keywords internal
#' @noRd
deprecate_warn_pkg <- function(
  when,
  what,
  with = NULL,
  details = NULL,
  id = NULL,
  env = rlang::caller_env(),
  user_env = rlang::caller_env()
) {
  deprecated_cnd <- NULL

  withCallingHandlers(
    lifecycle::deprecate_warn(
      when = when,
      what = what,
      with = with,
      details = details,
      id = id,
      env = env,
      user_env = user_env
    ),
    warning = function(w) {
      if (!inherits(w, "lifecycle_warning_deprecated")) {
        return(invisible(NULL))
      }

      deprecated_cnd <<- w
      tryInvokeRestart("muffleWarning")
      invisible(NULL)
    }
  )

  if (is.null(deprecated_cnd)) {
    return(invisible(NULL))
  }

  what_label <- as.character(what %||% "")
  with_label <- as.character(with %||% "")
  if (nzchar(what_label) && !grepl("`", what_label, fixed = TRUE)) {
    what_label <- paste0("`", what_label, "`")
  }
  if (nzchar(with_label) && !grepl("`", with_label, fixed = TRUE)) {
    with_label <- paste0("`", with_label, "`")
  }

  bullets <- c(
    "!" = paste0(what_label, " was deprecated in shinyOAuth ", when, "."),
    if (nzchar(with_label)) {
      stats::setNames(paste0("Please use ", with_label, " instead."), "i")
    } else {
      character()
    },
    normalize_bullets(details, default_type = "i")
  )

  warn_pkg(
    "Deprecated API",
    bullets,
    class = "lifecycle_warning_deprecated"
  )
}

#' Resolve an error header description from condition classes
#'
#' Used by `err_abort()` to pick the short description shown in the header.
#'
#' @param class_vec Condition class vector.
#' @return A short description string used in the error header.
#' @keywords internal
#' @noRd
short_desc_for_class <- function(class_vec) {
  known <- c(
    shinyOAuth_http_error = "HTTP request failed",
    shinyOAuth_transport_error = "Transport failure",
    shinyOAuth_dpop_nonce_error = "DPoP nonce challenge",
    shinyOAuth_state_error = "Invalid OAuth state",
    shinyOAuth_pkce_error = "PKCE validation failed",
    shinyOAuth_oidc_nonce_error = "OIDC nonce validation failed",
    shinyOAuth_token_error = "Token error",
    shinyOAuth_id_token_error = "ID token error",
    shinyOAuth_userinfo_error = "Userinfo request failed",
    shinyOAuth_userinfo_mismatch = "Userinfo does not match ID token",
    shinyOAuth_config_error = "Configuration error",
    shinyOAuth_input_error = "Invalid input",
    shinyOAuth_parse_error = "Parse error",
    shinyOAuth_error = "Error"
  )

  # Find first matching known class
  hit <- intersect(names(known), class_vec)

  # Return known description or generic fallback
  if (length(hit)) known[[hit[[1]]]] else "Miscellaneous error"
}

#' Normalize rlang error bullets
#'
#' Converts a message vector or list into the named character format expected
#' by [rlang::abort()]. Used by the error constructors in this file.
#'
#' @param msg Message vector or list.
#' @param default_type Bullet type assigned to unnamed entries.
#' @return A named character vector of bullets.
#' @keywords internal
#' @noRd
normalize_bullets <- function(msg, default_type = "!") {
  if (is.null(msg)) {
    return(character())
  }
  # Flatten one level if someone supplied list() of strings
  if (is.list(msg)) {
    msg <- unlist(msg, recursive = FALSE, use.names = TRUE)
  }
  # Preserve names across coercion to character (as.character() drops names)
  nm <- names(msg)
  if (!is.character(msg)) {
    msg <- as.character(msg)
    # Restore names if they were present prior to coercion
    if (!is.null(nm) && length(nm) == length(msg)) {
      names(msg) <- nm
    }
  }
  # Prepare names vector for bullet types
  nm <- names(msg)
  if (is.null(nm)) {
    nm <- rep_len("", length(msg))
  }
  # Fill empty or NA names with default bullet type
  nm[is.na(nm) | nm == ""] <- default_type
  stats::setNames(as.character(msg), nm)
}

# 2 Specialized error constructors ---------------------------------------------

## 2.1 HTTP and transport failures ---------------------------------------------

#' Abort with a typed HTTP error
#'
#' Builds an HTTP-flavored shinyOAuth condition from an httr2 response, extracts
#' safe structured details, emits the corresponding trace event, and aborts.
#' Used when a remote endpoint responds but the response still represents a
#' failure.
#'
#' @param msg Error message or rlang-style bullet vector.
#' @param resp Optional httr2 response object.
#' @param context Named list of structured context fields.
#' @param trace_id Optional trace id to reuse for the error.
#' @return No return value. This function always aborts.
#' @keywords internal
#' @noRd
err_http <- function(msg, resp = NULL, context = list(), trace_id = NULL) {
  trace_id <- resolve_trace_id(trace_id)
  expose <- isTRUE(allow_expose_error_body())
  status <- NA_integer_
  desc <- NULL
  url <- NULL
  body_snippet <- NULL
  if (!is.null(resp) && inherits(resp, "httr2_response")) {
    st <- try(httr2::resp_status(resp), silent = TRUE)
    status <- if (!inherits(st, "try-error") && length(st) == 1) {
      st
    } else {
      NA_integer_
    }
    desc <- try(httr2::resp_status_desc(resp), silent = TRUE)
    if (inherits(desc, "try-error")) {
      desc <- NULL
    }
    urlv <- try(httr2::resp_url(resp), silent = TRUE)
    url <- if (!inherits(urlv, "try-error") && length(urlv) == 1) {
      otel_http_url_full(urlv)
    } else {
      NULL
    }
    if (inherits(url, "try-error")) {
      url <- NULL
    }
    # Some callers reach err_http() before their usual parse-time body guard.
    check_resp_body_size(
      resp,
      context = if (is_valid_string(context[["phase"]])) {
        context[["phase"]]
      } else {
        "error response"
      }
    )
    if (expose) {
      body_snippet <- try(httr2::resp_body_string(resp), silent = TRUE)
      if (!inherits(body_snippet, "try-error")) {
        body_snippet <- sanitize_body(body_snippet)
      } else {
        body_snippet <- NULL
      }
    }
  }
  # Compute non-sensitive body digest for debugging if available
  # and extract RFC 6749 §5.2 structured error fields when present
  body_digest <- NULL
  oauth_error <- NULL
  oauth_error_description <- NULL
  oauth_error_uri <- NULL
  if (!is.null(resp) && inherits(resp, "httr2_response")) {
    bs <- try(httr2::resp_body_string(resp), silent = TRUE)
    if (!inherits(bs, "try-error")) {
      dig <- try(openssl::sha256(charToRaw(bs)), silent = TRUE)
      if (!inherits(dig, "try-error")) {
        body_digest <- paste0(sprintf("%02x", as.integer(dig)), collapse = "")
      }
      # RFC 6749 §5.2: try to extract structured error fields from JSON body
      parsed <- try(
        jsonlite::fromJSON(bs, simplifyVector = TRUE),
        silent = TRUE
      )
      if (!inherits(parsed, "try-error") && is.list(parsed)) {
        if (is_valid_string(parsed[["error"]])) {
          oauth_error <- parsed[["error"]]
        }
        if (is_valid_string(parsed[["error_description"]])) {
          oauth_error_description <- parsed[["error_description"]]
        }
        if (is_valid_string(parsed[["error_uri"]])) {
          oauth_error_uri <- otel_http_url_full(parsed[["error_uri"]])
        }
      }
    }
  }

  event_oauth_error_description <- if (isTRUE(expose)) {
    oauth_error_description
  } else {
    NULL
  }

  event <- c(
    list(
      type = "http_error",
      trace_id = trace_id,
      message = msg,
      status = status,
      url = url,
      body_digest = body_digest,
      oauth_error = oauth_error,
      oauth_error_description = event_oauth_error_description,
      oauth_error_uri = oauth_error_uri
    ),
    context
  )
  emit_trace_event(event)

  status_msg <- if (length(status) == 1 && !is.na(status)) {
    if (is_valid_string(desc)) {
      stats::setNames(paste0("Status ", status, ": ", desc, "."), "x")
    } else {
      stats::setNames(paste0("Status ", status, "."), "x")
    }
  } else {
    character()
  }
  # RFC 6749 §5.2: surface structured error fields from token endpoint
  oauth_error_msg <- if (!is.null(oauth_error)) {
    reason <- oauth_error
    if (!is.null(oauth_error_description)) {
      reason <- paste0(reason, ": ", oauth_error_description)
    }
    stats::setNames(paste0("OAuth error: ", reason), "x")
  } else {
    character()
  }
  oauth_error_uri_msg <- if (!is.null(oauth_error_uri)) {
    stats::setNames(paste0("Error URI: ", oauth_error_uri), "i")
  } else {
    character()
  }
  url_msg <- if (!is.null(url)) {
    stats::setNames(paste0("URL: ", url), "i")
  } else {
    character()
  }
  trace_msg <- c("i" = paste0("Trace ID: ", trace_id))
  body_msg <- if (expose && !is.null(body_snippet)) {
    stats::setNames(paste0("Body: ", body_snippet), "i")
  } else {
    character()
  }
  message <- format_condition_message(
    "HTTP request failed",
    c(msg, status_msg, oauth_error_msg, oauth_error_uri_msg, url_msg),
    footer = c(trace_msg, body_msg)
  )

  rlang::abort(
    message = message,
    class = c("shinyOAuth_http_error", "shinyOAuth_error"),
    trace_id = trace_id,
    status = status,
    url = url,
    body_digest = body_digest,
    oauth_error = oauth_error,
    oauth_error_description = oauth_error_description,
    oauth_error_uri = oauth_error_uri,
    context = context
  )
}

#' Abort with a typed transport error
#'
#' Builds a transport-flavored shinyOAuth condition for request failures that
#' did not produce an HTTP response. Used for network failures and timeouts.
#'
#' @param msg Error message or rlang-style bullet vector.
#' @param context Named list of structured context fields.
#' @param parent Optional parent condition.
#' @param trace_id Optional trace id to reuse for the error.
#' @return No return value. This function always aborts.
#' @keywords internal
#' @noRd
err_transport <- function(
  msg,
  context = list(),
  parent = NULL,
  trace_id = NULL
) {
  trace_id <- resolve_trace_id(trace_id)
  emit_trace_event(c(
    list(type = "transport_error", trace_id = trace_id, message = msg),
    context
  ))
  message <- format_condition_message(
    "Transport failure",
    c(msg, "x" = "No HTTP response was received."),
    footer = c("i" = paste0("Trace ID: ", trace_id))
  )
  rlang::abort(
    message = message,
    class = c("shinyOAuth_transport_error", "shinyOAuth_error"),
    trace_id = trace_id,
    context = context,
    parent = parent
  )
}

## 2.2 Typed wrapper constructors ----------------------------------------------

# Thin typed wrappers around err_abort() for the package's common error classes.
# Used throughout login, token, JWT, state, and HTTP helpers.

#' Raise an invalid state error
#'
#' Wraps `err_abort()` with the package state-error class. Used when stored or
#' returned OAuth state data is missing, expired, malformed, or does not match
#' the browser session.
#'
#' @param msg Error message or cli-style bullet vector.
#' @param context Named list of diagnostic fields attached to the condition.
#' @return This function does not return; it raises a condition.
#' @keywords internal
#' @noRd
err_invalid_state <- function(msg, context = list()) {
  err_abort(msg, class = "shinyOAuth_state_error", context = context)
}

#' Raise a PKCE error
#'
#' Wraps `err_abort()` with the package PKCE-error class. Used when the code
#' verifier or challenge values required for the OAuth login flow are invalid.
#'
#' @param msg Error message or cli-style bullet vector.
#' @param context Named list of diagnostic fields attached to the condition.
#' @return This function does not return; it raises a condition.
#' @keywords internal
#' @noRd
err_pkce <- function(msg, context = list()) {
  err_abort(msg, class = "shinyOAuth_pkce_error", context = context)
}

#' Raise an OIDC nonce error
#'
#' Wraps `err_abort()` with the package OIDC nonce-error class. Used when an
#' OpenID Connect nonce is missing or malformed.
#'
#' @param msg Error message or cli-style bullet vector.
#' @param context Named list of diagnostic fields attached to the condition.
#' @return This function does not return; it raises a condition.
#' @keywords internal
#' @noRd
err_oidc_nonce <- function(msg, context = list()) {
  err_abort(msg, class = "shinyOAuth_oidc_nonce_error", context = context)
}

#' Raise a token error
#'
#' Wraps `err_abort()` with the package token-error class. Used by token
#' exchange, refresh, revocation, introspection, and token response validation.
#'
#' @param msg Error message or cli-style bullet vector.
#' @param context Named list of diagnostic fields attached to the condition.
#' @return This function does not return; it raises a condition.
#' @keywords internal
#' @noRd
err_token <- function(msg, context = list()) {
  err_abort(msg, class = "shinyOAuth_token_error", context = context)
}

#' Raise an ID token error
#'
#' Wraps `err_abort()` with the package ID-token-error class. Used when an OIDC
#' ID token is missing, cannot be decoded, or fails claim or signature checks.
#'
#' @param msg Error message or cli-style bullet vector.
#' @param context Named list of diagnostic fields attached to the condition.
#' @return This function does not return; it raises a condition.
#' @keywords internal
#' @noRd
err_id_token <- function(msg, context = list()) {
  err_abort(msg, class = "shinyOAuth_id_token_error", context = context)
}

#' Raise a UserInfo error
#'
#' Wraps `err_abort()` with the package UserInfo-error class. Used when loading,
#' parsing, or validating a UserInfo response fails.
#'
#' @param msg Error message or cli-style bullet vector.
#' @param context Named list of diagnostic fields attached to the condition.
#' @return This function does not return; it raises a condition.
#' @keywords internal
#' @noRd
err_userinfo <- function(msg, context = list()) {
  err_abort(msg, class = "shinyOAuth_userinfo_error", context = context)
}

#' Raise a UserInfo subject mismatch error
#'
#' Wraps `err_abort()` with classes for a UserInfo response whose subject does
#' not match the ID token subject. Used after signed or plain UserInfo responses
#' are decoded.
#'
#' @param msg Error message or cli-style bullet vector.
#' @param context Named list of diagnostic fields attached to the condition.
#' @return This function does not return; it raises a condition.
#' @keywords internal
#' @noRd
err_userinfo_mismatch <- function(
  msg = "userinfo subject mismatch",
  context = list()
) {
  err_abort(
    msg,
    class = c("shinyOAuth_userinfo_mismatch", "shinyOAuth_userinfo_error"),
    context = context
  )
}

#' Raise a configuration error
#'
#' Wraps `err_abort()` with the package configuration-error class. Used when
#' caller settings, provider metadata, or package options are inconsistent.
#'
#' @param msg Error message or cli-style bullet vector.
#' @param context Named list of diagnostic fields attached to the condition.
#' @return This function does not return; it raises a condition.
#' @keywords internal
#' @noRd
err_config <- function(msg, context = list()) {
  err_abort(msg, class = "shinyOAuth_config_error", context = context)
}

#' Raise an input error
#'
#' Wraps `err_abort()` with the package input-error class. Used when a public
#' function receives an argument value that cannot be accepted.
#'
#' @param msg Error message or cli-style bullet vector.
#' @param context Named list of diagnostic fields attached to the condition.
#' @return This function does not return; it raises a condition.
#' @keywords internal
#' @noRd
err_input <- function(msg, context = list()) {
  err_abort(msg, class = "shinyOAuth_input_error", context = context)
}

#' Raise a parse error
#'
#' Wraps `err_abort()` with the package parse-error class. Used when JSON, JWT,
#' JWKS, form, or other structured data cannot be decoded safely.
#'
#' @param msg Error message or cli-style bullet vector.
#' @param context Named list of diagnostic fields attached to the condition.
#' @return This function does not return; it raises a condition.
#' @keywords internal
#' @noRd
err_parse <- function(msg, context = list()) {
  err_abort(msg, class = "shinyOAuth_parse_error", context = context)
}

## 2.3 Other helpers -----------------------------------------------------------

#' Sanitize an HTTP response body preview
#'
#' Used by `err_http()` when body exposure is enabled for development.
#'
#' @param body Response body text to sanitize.
#' @param max_chars Maximum number of bytes to keep before truncation.
#' @return A sanitized preview string.
#' @keywords internal
#' @noRd
sanitize_body <- function(body, max_chars = 200) {
  if (is.null(body) || is.na(body)) {
    return("")
  }
  body <- as.character(body)
  body <- gsub("\n|\r", " ", body)
  if (nchar(body, type = "bytes") > max_chars) {
    paste0(substr(body, 1, max_chars), "... [truncated]")
  } else {
    body
  }
}

Try the shinyOAuth package in your browser

Any scripts or data that you put into this service are public.

shinyOAuth documentation built on May 23, 2026, 9:06 a.m.