R/utils__crypt_state.R

Defines functions state_cache_key state_decrypt_gcm state_encrypt_gcm state_decrypt_fail state_decrypt_delay_before_fail get_option_env_positive_number normalize_key32

# This file contains the encryption helpers for the sealed OAuth state
# payload
# The state value is the temporary login data sent out during redirect and
# checked again on callback
# Used for encrypting that state into a compact token and decrypting it safely
# during callback handling

# 1 State encryption helpers ---------------------------------------------------

## 1.1 Encrypt and decrypt sealed state ----------------------------------------

# Functions in this subsection encrypt state payloads before login redirects and
# decrypt them again during callback handling.

#' Internal: normalize or derive a 32-byte state encryption key
#'
#' Accepts either a sufficiently long character passphrase or a raw key.
#' Character inputs are UTF-8 normalized and derived with SHA-256; raw inputs
#' of exactly 32 bytes are used as-is, and longer raw inputs are hashed to
#' avoid silent truncation. Used by the state encrypt/decrypt helpers below.
#'
#' @param key Character passphrase or raw key material.
#' @param min_chars Minimum allowed passphrase length for character keys.
#' @return Raw 32-byte encryption key.
#' @keywords internal
#' @noRd
normalize_key32 <- function(key, min_chars = 32L) {
  if (is.null(key)) {
    err_config("state key is NULL", context = list(phase = "key_derivation"))
  }
  if (is.character(key)) {
    if (!is_valid_string(key)) {
      err_config(
        "state key must be a non-empty single string",
        context = list(phase = "key_derivation")
      )
    }

    # Ensure passphrase strength before derivation
    if (nchar(key, type = "bytes") < as.integer(min_chars)) {
      err_config(
        sprintf(
          "state key must be at least %d characters; got %d",
          as.integer(min_chars),
          nchar(key, type = "bytes")
        ),
        context = list(
          phase = "key_derivation",
          min_chars = as.integer(min_chars)
        )
      )
    }

    # Derive 32-byte key; normalize to UTF-8 to avoid locale-dependent bytes
    key <- openssl::sha256(charToRaw(enc2utf8(key)))
  } else if (is.raw(key)) {
    # Raw key path: enforce >= 32 bytes; use exact 32 as-is; hash if longer
    # Rationale: truncation discards entropy and may surprise operators who
    # paste 64-byte secrets. Hashing preserves full-entropy contribution and
    # yields a deterministic 32-byte key.
    if (length(key) < 32L) {
      err_config(
        sprintf(
          "raw state key must be at least 32 bytes; got %d",
          length(key)
        ),
        context = list(phase = "key_derivation")
      )
    }
    if (length(key) == 32L) {
      # Use provided 32 random bytes directly (highest entropy, no transform)
      key <- key
    } else {
      # For raw inputs > 32 bytes, derive a 32-byte key via SHA-256 to avoid
      # silent entropy loss from truncation and ensure deterministic derivation.
      key <- openssl::sha256(key)
    }
  } else {
    err_config(
      "state key must be character or raw",
      context = list(phase = "key_derivation")
    )
  }
  key
}

#' Internal: read a positive numeric value from option or environment
#'
#' Used by `state_decrypt_gcm()` for defensive size limits where package
#' options should take precedence over environment-variable fallbacks.
#'
#' @param opt_name Option name to read first.
#' @param env_name Fallback environment variable name.
#' @param default Positive numeric default.
#' @return Positive numeric limit value.
#' @keywords internal
#' @noRd
get_option_env_positive_number <- function(opt_name, env_name, default) {
  val <- getOption(opt_name, NULL)
  if (is.null(val)) {
    env <- Sys.getenv(env_name, unset = NA_character_)
    if (!is.na(env) && nzchar(env)) {
      suppressWarnings(val <- as.numeric(env))
    }
  }
  if (
    !is.numeric(val) ||
      length(val) != 1L ||
      is.na(val) ||
      !is.finite(val) ||
      val <= 0
  ) {
    return(as.numeric(default))
  }
  as.numeric(val)
}

#' Internal: add a tiny randomized delay before state decryption failure
#'
#' Used by `state_decrypt_fail()` to reduce timing differences between state
#' parsing and decryption failure paths.
#'
#' @return No return value; may sleep briefly before returning invisibly.
#' @keywords internal
#' @noRd
state_decrypt_delay_before_fail <- function() {
  bounds <- getOption("shinyOAuth.state_fail_delay_ms", c(10, 30))
  ms <- 0
  if (is.numeric(bounds) && length(bounds) >= 1) {
    b1 <- suppressWarnings(as.numeric(bounds[1]))
    if (!is.finite(b1) || is.na(b1) || b1 < 0) {
      b1 <- 0
    }
    if (length(bounds) >= 2) {
      b2 <- suppressWarnings(as.numeric(bounds[2]))
      if (!is.finite(b2) || is.na(b2) || b2 < 0) {
        b2 <- b1
      }
      lo <- min(b1, b2)
      hi <- max(b1, b2)
      ms <- stats::runif(1, min = lo, max = hi)
    } else {
      ms <- b1
    }
  }
  if (is.finite(ms) && !is.na(ms) && ms > 0) {
    Sys.sleep(ms / 1000)
  }
  invisible(NULL)
}

#' Internal: raise a normalized invalid-state error during state decryption
#'
#' Used by `state_decrypt_gcm()` so all invalid-state failures pass through the
#' same delay and `err_invalid_state()` path.
#'
#' @param msg Invalid-state message.
#' @param context Structured error context.
#' @return No return value; always raises `err_invalid_state()`.
#' @keywords internal
#' @noRd
state_decrypt_fail <- function(msg, context = list()) {
  state_decrypt_delay_before_fail()
  err_invalid_state(msg, context = context)
}

#' Internal: encrypt a state payload into the compact GCM envelope
#'
#' Serializes the payload as JSON, encrypts it with AES-GCM, and returns the
#' package's base64url-wrapped state token format containing version, IV, tag,
#' and ciphertext. Used when login state is created before redirect.
#'
#' @param payload State payload to encrypt.
#' @param key Character passphrase or raw key material.
#' @param version Envelope version number.
#' @param min_key_chars Minimum passphrase length for character keys.
#' @return Compact encrypted state token string.
#' @keywords internal
#' @noRd
state_encrypt_gcm <- function(payload, key, version = 1L, min_key_chars = 32L) {
  if (is.null(payload)) {
    err_input(c("x" = "payload is NULL"), context = list(phase = "encrypt"))
  }
  key <- normalize_key32(key, min_chars = min_key_chars)

  json <- jsonlite::toJSON(
    payload,
    auto_unbox = TRUE,
    digits = NA,
    null = "null"
  )
  if (!is_valid_string(json)) {
    err_input(
      c("x" = "payload serialized to empty JSON string"),
      context = list(phase = "encrypt")
    )
  }

  iv <- openssl::rand_bytes(12L) # 96-bit IV for GCM

  enc <- openssl::aes_gcm_encrypt(charToRaw(json), key = key, iv = iv)

  # Handle both return shapes (list with $data/$tag or raw(ct||tag))
  if (is.list(enc) && !is.null(enc$data) && !is.null(enc$tag)) {
    ct <- enc$data
    tag <- enc$tag
  } else if (is.raw(enc) && !is.null(attr(enc, "tag", exact = TRUE))) {
    # Some versions return ciphertext as raw with tag attribute
    ct <- enc
    tag <- attr(enc, "tag", exact = TRUE)
    if (!is.raw(tag) || length(tag) != 16L) {
      err_config(
        c("x" = "Unexpected GCM tag attribute length"),
        context = list(phase = "encrypt")
      )
    }
  } else if (is.raw(enc)) {
    n <- length(enc)
    if (n < 16L) {
      err_invalid_state(
        c("x" = "ciphertext too short"),
        context = list(phase = "encrypt")
      )
    }
    if (n == 16L) {
      # zero-length ciphertext, tag only
      tag <- enc
      ct <- raw(0)
    } else {
      tag <- enc[(n - 15L):n]
      ct <- enc[1:(n - 16L)]
    }
  } else {
    err_config(
      c("x" = "Unexpected return type from aes_gcm_encrypt()"),
      context = list(phase = "encrypt")
    )
  }

  token_obj <- list(
    v = as.integer(version),
    iv = base64url_encode(iv),
    tg = base64url_encode(tag),
    ct = base64url_encode(ct)
  )
  base64url_encode(charToRaw(jsonlite::toJSON(token_obj, auto_unbox = TRUE)))
}

#' Internal: decrypt and validate the compact state GCM envelope
#'
#' Decodes the outer base64url wrapper, validates the version and envelope
#' members, decrypts the ciphertext with AES-GCM, and returns the parsed JSON
#' payload. The helper enforces size caps and emits audit events for parse
#' failures without disclosing plaintext or key material. Used when callback
#' handling resumes after the provider redirects back.
#'
#' @param token Compact encrypted state token.
#' @param key Character passphrase or raw key material.
#' @param expected_version Expected envelope version.
#' @param min_key_chars Minimum passphrase length for character keys.
#' @return Parsed decrypted state payload list.
#' @keywords internal
#' @noRd
state_decrypt_gcm <- function(
  token,
  key,
  expected_version = 1L,
  min_key_chars = 32L
) {
  # Hard caps
  max_token_chars <- get_option_env_positive_number(
    "shinyOAuth.state_max_token_chars",
    "shinyOAuth_STATE_MAX_TOKEN_CHARS",
    8192
  )
  max_wrapper_bytes <- get_option_env_positive_number(
    "shinyOAuth.state_max_wrapper_bytes",
    "shinyOAuth_STATE_MAX_WRAPPER_BYTES",
    8192
  )
  max_ct_b64_chars <- get_option_env_positive_number(
    "shinyOAuth.state_max_ct_b64_chars",
    "shinyOAuth_STATE_MAX_CT_B64_CHARS",
    8192
  )
  max_ct_bytes <- get_option_env_positive_number(
    "shinyOAuth.state_max_ct_bytes",
    "shinyOAuth_STATE_MAX_CT_BYTES",
    8192
  )

  # Internal helper: emit an audit event for a parse or decrypt failure.
  # Used only by `state_decrypt_gcm()` so failure reasons are logged without
  # leaking plaintext or key material.
  # @param reason_code Stable failure reason.
  # @param details Additional redacted context fields.
  # @return No return value; emits a best-effort audit event and returns
  #   invisibly.
  audit_fail <- function(reason_code, details = list()) {
    ctx <- c(
      list(
        phase = "decrypt",
        reason = as.character(reason_code),
        token_digest = try(string_digest(token), silent = TRUE)
      ),
      details
    )
    # Best-effort: never interfere with control flow
    try(audit_event("state_parse_failure", context = ctx), silent = TRUE)
    invisible(NULL)
  }

  state_fail <- state_decrypt_fail

  if (!is_valid_string(token)) {
    audit_fail("token_not_string")
    state_fail(
      "token must be a non-empty single string",
      context = list(phase = "decrypt")
    )
  }
  # Preemptively cap the base64url string length to avoid excessive decode work
  token_len <- nchar(token, type = "bytes")
  if (token_len > max_token_chars) {
    audit_fail(
      "token_b64_too_large",
      details = list(length = token_len, limit = max_token_chars)
    )
    state_fail(
      "state token too large",
      context = list(phase = "decrypt", where = "token_b64")
    )
  }
  key <- normalize_key32(key, min_chars = min_key_chars)

  decoded <- try(base64url_decode_raw(token), silent = TRUE)
  if (inherits(decoded, "try-error")) {
    audit_fail("token_b64_invalid")
    state_fail(
      "state token is not valid base64",
      context = list(phase = "decrypt")
    )
  }
  # Cap decoded wrapper size before JSON parsing
  if (length(decoded) > max_wrapper_bytes) {
    audit_fail(
      "token_wrapper_too_large",
      details = list(length = length(decoded), limit = max_wrapper_bytes)
    )
    state_fail(
      "state token wrapper too large",
      context = list(phase = "decrypt", where = "wrapper_raw")
    )
  }
  # JSON text cannot contain embedded NUL bytes. Without this guard,
  # rawToChar() may truncate at NUL and accidentally accept appended garbage.
  if (any(decoded == as.raw(0))) {
    audit_fail("token_payload_embedded_nul")
    state_fail(
      "state token payload is not valid JSON",
      context = list(phase = "decrypt")
    )
  }
  payload_json <- try(rawToChar(decoded), silent = TRUE)
  if (inherits(payload_json, "try-error")) {
    audit_fail("token_payload_utf8_invalid")
    state_fail(
      "state token payload is not valid UTF-8",
      context = list(phase = "decrypt")
    )
  }
  obj <- try(
    jsonlite::fromJSON(payload_json, simplifyVector = FALSE),
    silent = TRUE
  )
  # Ensure predictable structure: must be a named list (not data.frame)
  if (
    inherits(obj, "try-error") ||
      !is.list(obj) ||
      is.data.frame(obj) ||
      is.null(names(obj))
  ) {
    audit_fail("token_payload_json_invalid")
    state_fail(
      "state token payload is not valid JSON",
      context = list(phase = "decrypt")
    )
  }
  if (!identical(as.integer(obj$v), as.integer(expected_version))) {
    audit_fail(
      "token_version_mismatch",
      details = list(
        found_version = as.integer(obj$v),
        expected_version = as.integer(expected_version)
      )
    )
    state_fail(
      "state token version mismatch",
      context = list(phase = "decrypt")
    )
  }

  if (!is_valid_string(obj$iv)) {
    audit_fail("iv_missing")
    state_fail("state token missing IV", context = list(phase = "decrypt"))
  }
  iv <- try(base64url_decode_raw(obj$iv), silent = TRUE)
  if (inherits(iv, "try-error")) {
    audit_fail("iv_b64_invalid")
    state_fail(
      "state token IV is not valid base64",
      context = list(phase = "decrypt")
    )
  }
  if (length(iv) != 12L) {
    audit_fail("iv_len_invalid", details = list(iv_len = length(iv)))
    state_fail(
      sprintf("invalid GCM IV length: %d", length(iv)),
      context = list(phase = "decrypt")
    )
  }
  if (!is_valid_string(obj$tg)) {
    audit_fail("tag_missing")
    state_fail("state token missing tag", context = list(phase = "decrypt"))
  }
  tg <- try(base64url_decode_raw(obj$tg), silent = TRUE)
  if (inherits(tg, "try-error")) {
    audit_fail("tag_b64_invalid")
    state_fail(
      "state token tag is not valid base64",
      context = list(phase = "decrypt")
    )
  }
  if (length(tg) != 16L) {
    audit_fail("tag_len_invalid", details = list(tag_len = length(tg)))
    state_fail(
      sprintf("invalid GCM tag length: %d", length(tg)),
      context = list(phase = "decrypt")
    )
  }
  if (!is_valid_string(obj$ct)) {
    audit_fail("ciphertext_missing")
    state_fail(
      "state token missing ciphertext",
      context = list(phase = "decrypt")
    )
  }
  # Cap ciphertext base64 length before attempting to decode
  ct_b64_len <- try(nchar(obj$ct, type = "bytes"), silent = TRUE)
  if (
    !inherits(ct_b64_len, "try-error") &&
      is.numeric(ct_b64_len) &&
      ct_b64_len > max_ct_b64_chars
  ) {
    audit_fail(
      "ciphertext_b64_too_large",
      details = list(length = ct_b64_len, limit = max_ct_b64_chars)
    )
    state_fail(
      "state token ciphertext too large",
      context = list(phase = "decrypt", where = "ct_b64")
    )
  }
  ct <- try(base64url_decode_raw(obj$ct), silent = TRUE)
  if (inherits(ct, "try-error")) {
    audit_fail("ciphertext_b64_invalid")
    state_fail(
      "state token ciphertext is not valid base64",
      context = list(phase = "decrypt")
    )
  }
  if (length(ct) < 1L) {
    audit_fail("ciphertext_empty")
    state_fail("empty ciphertext", context = list(phase = "decrypt"))
  }
  # Cap decoded ciphertext size to avoid expensive GCM on large inputs
  if (length(ct) > max_ct_bytes) {
    audit_fail(
      "ciphertext_too_large",
      details = list(length = length(ct), limit = max_ct_bytes)
    )
    state_fail(
      "state token ciphertext too large",
      context = list(phase = "decrypt", where = "ct_raw")
    )
  }

  # 3-arg API expects data = ct||tag
  res <- try(
    openssl::aes_gcm_decrypt(data = c(ct, tg), key = key, iv = iv),
    silent = TRUE
  )
  if (inherits(res, "try-error")) {
    audit_fail("gcm_auth_failed")
    state_fail(
      c(
        "x" = "GCM authentication failed",
        "!" = "This often indicates the state key/secret does not match the one used to encrypt the state (e.g., OAuthClient created inside a Shiny session so the key changes on redirect/new session, different Shiny worker, or rotated secret)."
      ),
      context = list(phase = "decrypt")
    )
  }
  # Decrypted wrapper payload is JSON text; reject embedded NULs to avoid
  # truncation-acceptance edge cases.
  if (any(res == as.raw(0))) {
    audit_fail("decrypted_payload_embedded_nul")
    state_fail(
      c(
        "x" = "state token decrypted payload is not valid JSON",
        "!" = "This can happen if the state key/secret is wrong (e.g., OAuthClient created inside a Shiny session so the key changes on redirect/new session, different Shiny worker, or rotated secret); the decrypted bytes won't decode as JSON."
      ),
      context = list(phase = "decrypt")
    )
  }
  parsed <- try(
    jsonlite::fromJSON(rawToChar(res), simplifyVector = FALSE),
    silent = TRUE
  )
  if (
    inherits(parsed, "try-error") || !is.list(parsed) || is.data.frame(parsed)
  ) {
    audit_fail("decrypted_json_invalid")
    state_fail(
      c(
        "x" = "state token decrypted payload is not valid JSON",
        "!" = "This can happen if the state key/secret is wrong (e.g., OAuthClient created inside a Shiny session so the key changes on redirect/new session, different Shiny worker, or rotated secret); the decrypted bytes won't decode as JSON."
      ),
      context = list(phase = "decrypt")
    )
  }
  # Normalize and validate decrypted payload shape
  # - Must be a named list so downstream validation can rely on names
  if (is.null(names(parsed))) {
    audit_fail("decrypted_json_unnamed_list")
    state_fail(
      "state token decrypted payload must be an object with named fields",
      context = list(phase = "decrypt")
    )
  }
  # Scopes are expected downstream as a character vector; preserve empty as character(0)
  if (!is.null(parsed$scopes)) {
    sc <- parsed$scopes
    # If parsed with simplifyVector = FALSE, JSON arrays become lists; convert list-of-length-one strings to character vector
    if (is.list(sc)) {
      ok <- vapply(
        sc,
        function(el) is.character(el) && length(el) == 1L && !is.na(el),
        logical(1)
      )
      if (length(sc) == 0L) {
        parsed$scopes <- character()
      } else if (all(ok)) {
        parsed$scopes <- vapply(sc, function(el) as.character(el), character(1))
      } else if (is.character(sc)) {
        # no-op
      } else {
        # Leave as-is; downstream validation will reject incompatible types
        parsed$scopes <- sc
      }
    } else if (is.null(sc)) {
      parsed$scopes <- character()
    } else if (is.character(sc)) {
      # already character vector
    } else {
      # Any other type left as-is for downstream validators to handle
    }
  }
  parsed
}

# 2 State cache keys -----------------------------------------------------------

#' Derive a cache key for an OAuth state value
#'
#' cachem only allows lowercase letters and digits in keys. We preserve the
#' original high-entropy state (mixed-case base64url) in the encrypted payload
#' and store/retrieve associated data under a deterministic lowercase-hex
#' SHA-256 of that state.
#'
#' @param state OAuth state string.
#' @return Lowercase hex cache key.
#' @keywords internal
#' @noRd
state_cache_key <- function(state) {
  if (!is.character(state) || length(state) != 1L || !nzchar(state)) {
    # Audit malformed state identifiers used for cache lookups
    try(
      audit_event(
        "state_parse_failure",
        context = list(
          phase = "cache_key",
          reason = "state_not_string",
          state_digest = try(string_digest(state), silent = TRUE)
        )
      ),
      silent = TRUE
    )
    err_invalid_state(
      "state_cache_key: state must be a non-empty single string",
      context = list(phase = "cache_key")
    )
  }
  raw_to_hex_lower(openssl::sha256(charToRaw(state)))
}

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.