add files

R/asa_api_helpers.R

@@ -300,11 +300,74 @@ asa_api_secret_env_value <- function(name) {
   trimws(Sys.getenv(asa_api_scalar_chr(name, default = ""), unset = ""))
 }
 
+asa_api_error_fields <- function(message, error_code = NULL, details = NULL) {
+  payload <- list(
+    status = "error",
+    error = asa_api_scalar_chr(message, default = "Request failed.")
+  )
+
+  code <- asa_api_scalar_chr(error_code, default = "")
+  if (nzchar(code)) {
+    payload$error_code <- code
+  }
+
+  if (is.list(details) && length(details)) {
+    payload$details <- details
+  }
+
+  payload
+}
+
 asa_api_missing_auth_env_vars <- function() {
   required <- c("ASA_API_BEARER_TOKEN", "GUI_PASSWORD")
   required[!nzchar(vapply(required, asa_api_secret_env_value, character(1)))]
 }
 
+asa_api_extract_missing_auth_env_vars <- function(message = NULL) {
+  text <- asa_api_scalar_chr(message, default = "")
+  matches <- regmatches(
+    text,
+    gregexpr("`[^`]+`", text, perl = TRUE)
+  )[[1]]
+  parsed <- if (length(matches) && !identical(matches, character(0))) {
+    gsub("^`|`$", "", matches)
+  } else {
+    character(0)
+  }
+
+  sort(unique(c(parsed, asa_api_missing_auth_env_vars())))
+}
+
+asa_api_is_auth_config_error <- function(message = NULL) {
+  grepl(
+    "^Missing required authentication environment variable\\(s\\):",
+    asa_api_scalar_chr(message, default = "")
+  )
+}
+
+asa_api_boot_failure <- function(boot_error = NULL) {
+  text <- trimws(asa_api_scalar_chr(boot_error, default = ""))
+  if (!nzchar(text)) {
+    return(NULL)
+  }
+
+  if (isTRUE(asa_api_is_auth_config_error(text))) {
+    return(list(
+      status_code = 503L,
+      message = "Service unavailable: authentication is not configured.",
+      error_code = "auth_config_missing",
+      details = list(
+        missing_env_vars = asa_api_extract_missing_auth_env_vars(text)
+      )
+    ))
+  }
+
+  list(
+    status_code = 503L,
+    message = "Service unavailable."
+  )
+}
+
 asa_api_refresh_auth_cache <- function(force = FALSE) {
   cached_api_hash <- .asa_api_auth_cache$api_bearer_token_hash %||% ""
   cached_gui_hash <- .asa_api_auth_cache$gui_password_hash %||% ""
@@ -336,21 +399,49 @@ asa_api_refresh_auth_cache <- function(force = FALSE) {
   invisible(TRUE)
 }
 
-asa_api_verify_secret <- function(candidate, cache_key) {
+asa_api_auth_check_secret <- function(candidate, cache_key, auth_target) {
   supplied <- asa_api_scalar_chr(candidate, default = "")
-  if (!nzchar(supplied)) {
-    return(FALSE)
-  }
+  refresh_error <- NULL
 
-  tryCatch(
+  auth_result <- tryCatch(
     {
       asa_api_refresh_auth_cache()
       stored_hash <- .asa_api_auth_cache[[asa_api_scalar_chr(cache_key, default = "")]] %||% ""
-      is.character(stored_hash) &&
-        nzchar(stored_hash) &&
-        isTRUE(sodium::password_verify(stored_hash, supplied))
+      if (nzchar(supplied) &&
+          is.character(stored_hash) &&
+          nzchar(stored_hash) &&
+          isTRUE(sodium::password_verify(stored_hash, supplied))) {
+        return(list(ok = TRUE))
+      }
+
+      list(
+        ok = FALSE,
+        status_code = 401L,
+        message = "Unauthorized: provided credential did not match the configured value.",
+        error_code = "credential_mismatch",
+        details = list(
+          auth_target = asa_api_scalar_chr(auth_target, default = "")
+        )
+      )
     },
-    error = function(e) FALSE
+    error = function(e) {
+      refresh_error <<- conditionMessage(e)
+      NULL
+    }
+  )
+  if (!is.null(auth_result)) {
+    return(auth_result)
+  }
+
+  boot_failure <- asa_api_boot_failure(refresh_error)
+  if (!is.null(boot_failure)) {
+    return(c(list(ok = FALSE), boot_failure))
+  }
+
+  list(
+    ok = FALSE,
+    status_code = 503L,
+    message = "Service unavailable."
   )
 }
 
@@ -368,15 +459,28 @@ asa_api_extract_bearer_token <- function(req) {
   ""
 }
 
-asa_api_has_required_bearer_token <- function(req) {
-  asa_api_verify_secret(
+asa_api_check_bearer_token <- function(req) {
+  asa_api_auth_check_secret(
     asa_api_extract_bearer_token(req),
-    "api_bearer_token_hash"
+    "api_bearer_token_hash",
+    "api_bearer_token"
+  )
+}
+
+asa_api_has_required_bearer_token <- function(req) {
+  isTRUE(asa_api_check_bearer_token(req)$ok)
+}
+
+asa_api_check_gui_password <- function(password) {
+  asa_api_auth_check_secret(
+    password,
+    "gui_password_hash",
+    "gui_password"
   )
 }
 
 asa_api_has_required_gui_password <- function(password) {
-  asa_api_verify_secret(password, "gui_password_hash")
+  isTRUE(asa_api_check_gui_password(password)$ok)
 }
 
 asa_api_require_prompt <- function(payload) {

R/plumber.R

@@ -39,9 +39,23 @@ tryCatch(
   }
 )
 
-asa_api_error_payload <- function(res, status, message) {
+asa_api_error_payload <- function(res, status, message, error_code = NULL, details = NULL) {
   res$status <- as.integer(status)
-  list(status = "error", error = asa_api_scalar_chr(message, default = "Request failed."))
+  asa_api_error_fields(
+    message,
+    error_code = error_code,
+    details = details
+  )
+}
+
+asa_api_failure_payload <- function(res, failure) {
+  asa_api_error_payload(
+    res,
+    failure$status_code %||% 500L,
+    failure$message %||% "Request failed.",
+    error_code = failure$error_code %||% NULL,
+    details = failure$details %||% NULL
+  )
 }
 
 asa_api_error_status <- function(message) {
@@ -76,12 +90,14 @@ function(req, res) {
     return(plumber::forward())
   }
 
-  if (is.character(.asa_api_boot_error) && nzchar(trimws(.asa_api_boot_error))) {
-    return(asa_api_error_payload(res, 503L, "Service unavailable."))
+  boot_failure <- asa_api_boot_failure(.asa_api_boot_error)
+  if (!is.null(boot_failure)) {
+    return(asa_api_failure_payload(res, boot_failure))
   }
 
-  if (!asa_api_has_required_bearer_token(req)) {
-    return(asa_api_error_payload(res, 401L, "Unauthorized."))
+  auth_check <- asa_api_check_bearer_token(req)
+  if (!isTRUE(auth_check$ok)) {
+    return(asa_api_failure_payload(res, auth_check))
   }
 
   plumber::forward()
@@ -108,8 +124,9 @@ function() {
 #* @post /v1/run
 #* @serializer unboxedJSON
 function(req, res) {
-  if (is.character(.asa_api_boot_error) && nzchar(trimws(.asa_api_boot_error))) {
-    return(asa_api_error_payload(res, 503L, "Service unavailable."))
+  boot_failure <- asa_api_boot_failure(.asa_api_boot_error)
+  if (!is.null(boot_failure)) {
+    return(asa_api_failure_payload(res, boot_failure))
   }
 
   parse_error <- NULL
@@ -137,8 +154,9 @@ function(req, res) {
 #* @post /v1/batch
 #* @serializer unboxedJSON
 function(req, res) {
-  if (is.character(.asa_api_boot_error) && nzchar(trimws(.asa_api_boot_error))) {
-    return(asa_api_error_payload(res, 503L, "Service unavailable."))
+  boot_failure <- asa_api_boot_failure(.asa_api_boot_error)
+  if (!is.null(boot_failure)) {
+    return(asa_api_failure_payload(res, boot_failure))
   }
 
   parse_error <- NULL
@@ -166,8 +184,9 @@ function(req, res) {
 #* @post /gui/query
 #* @serializer unboxedJSON
 function(req, res) {
-  if (is.character(.asa_api_boot_error) && nzchar(trimws(.asa_api_boot_error))) {
-    return(asa_api_error_payload(res, 503L, "Service unavailable."))
+  boot_failure <- asa_api_boot_failure(.asa_api_boot_error)
+  if (!is.null(boot_failure)) {
+    return(asa_api_failure_payload(res, boot_failure))
   }
 
   parse_error <- NULL
@@ -182,8 +201,9 @@ function(req, res) {
     return(asa_api_error_payload(res, 400L, parse_error))
   }
 
-  if (!asa_api_has_required_gui_password(payload$password)) {
-    return(asa_api_error_payload(res, 401L, "Unauthorized."))
+  auth_check <- asa_api_check_gui_password(payload$password)
+  if (!isTRUE(auth_check$ok)) {
+    return(asa_api_failure_payload(res, auth_check))
   }
 
   payload$include_raw_output <- FALSE

README.md

@@ -33,6 +33,9 @@ It uses:
 - GUI auth is password-based:
   - `/gui/query` verifies the submitted password against an in-memory hash derived from `GUI_PASSWORD`
 - The service fails closed if either auth secret env var is missing or blank.
+- Auth errors are diagnostic but safe:
+  - missing auth env vars return `503` with `error_code: "auth_config_missing"` and `details.missing_env_vars`
+  - wrong GUI/API credentials return `401` with `error_code: "credential_mismatch"` and `details.auth_target`
 
 ## Required Environment Variables
 

Tests/api_contract_smoke.R

@@ -170,6 +170,38 @@ assert_true(
   identical(asa_api_missing_auth_env_vars(), character(0)),
   "Auth bootstrap should require explicit bearer-token and GUI-password env vars."
 )
+auth_config_boot_failure <- asa_api_boot_failure(
+  "Missing required authentication environment variable(s): `GUI_PASSWORD`, `ASA_API_BEARER_TOKEN`."
+)
+assert_true(
+  identical(auth_config_boot_failure$status_code, 503L) &&
+    identical(auth_config_boot_failure$error_code, "auth_config_missing") &&
+    identical(
+      sort(auth_config_boot_failure$details$missing_env_vars),
+      sort(c("GUI_PASSWORD", "ASA_API_BEARER_TOKEN"))
+    ),
+  "Boot failures caused by missing auth env vars should expose a structured safe error."
+)
+generic_boot_failure <- asa_api_boot_failure("Package `asa` is not installed in this environment.")
+assert_true(
+  identical(generic_boot_failure$status_code, 503L) &&
+    identical(generic_boot_failure$message, "Service unavailable.") &&
+    is.null(generic_boot_failure$error_code),
+  "Non-auth boot failures should remain generic in request responses."
+)
+auth_config_payload <- asa_api_error_fields(
+  auth_config_boot_failure$message,
+  auth_config_boot_failure$error_code,
+  auth_config_boot_failure$details
+)
+assert_true(
+  identical(auth_config_payload$error_code, "auth_config_missing") &&
+    identical(
+      sort(auth_config_payload$details$missing_env_vars),
+      sort(c("GUI_PASSWORD", "ASA_API_BEARER_TOKEN"))
+    ),
+  "Structured auth-config failures should render with error_code and missing_env_vars details."
+)
 assert_true(
   is.character(.asa_api_auth_cache$api_bearer_token_hash) &&
     nzchar(.asa_api_auth_cache$api_bearer_token_hash) &&
@@ -218,9 +250,35 @@ assert_true(
   isTRUE(asa_api_has_required_gui_password(auth_fixture[["GUI_PASSWORD"]])),
   "GUI auth should accept the configured password."
 )
+gui_mismatch <- asa_api_check_gui_password("wrong-password")
+assert_true(
+  identical(gui_mismatch$ok, FALSE) &&
+    identical(gui_mismatch$status_code, 401L) &&
+    identical(gui_mismatch$error_code, "credential_mismatch") &&
+    identical(gui_mismatch$details$auth_target, "gui_password"),
+  "GUI auth should report credential mismatches with a structured safe error."
+)
+gui_mismatch_payload <- asa_api_error_fields(
+  gui_mismatch$message,
+  gui_mismatch$error_code,
+  gui_mismatch$details
+)
+assert_true(
+  identical(
+    gui_mismatch_payload$error,
+    "Unauthorized: provided credential did not match the configured value."
+  ) &&
+    identical(gui_mismatch_payload$error_code, "credential_mismatch") &&
+    identical(gui_mismatch_payload$details$auth_target, "gui_password"),
+  "GUI credential mismatches should render the expected response fields."
+)
+api_mismatch <- asa_api_check_bearer_token(mock_request(authorization = "Bearer wrong"))
 assert_true(
-  !isTRUE(asa_api_has_required_gui_password("wrong-password")),
-  "GUI auth should reject the wrong password."
+  identical(api_mismatch$ok, FALSE) &&
+    identical(api_mismatch$status_code, 401L) &&
+    identical(api_mismatch$error_code, "credential_mismatch") &&
+    identical(api_mismatch$details$auth_target, "api_bearer_token"),
+  "API auth should report bearer-token mismatches with a structured safe error."
 )
 
 asa_api_clear_auth_cache()
@@ -229,6 +287,14 @@ expect_error_contains(
   asa_api_refresh_auth_cache(force = TRUE),
   "ASA_API_BEARER_TOKEN"
 )
+gui_missing_auth_config <- asa_api_check_gui_password("anything")
+assert_true(
+  identical(gui_missing_auth_config$ok, FALSE) &&
+    identical(gui_missing_auth_config$status_code, 503L) &&
+    identical(gui_missing_auth_config$error_code, "auth_config_missing") &&
+    identical(gui_missing_auth_config$details$missing_env_vars, "ASA_API_BEARER_TOKEN"),
+  "Missing auth env vars should surface as structured startup misconfiguration errors."
+)
 do.call(Sys.setenv, stats::setNames(list(auth_fixture[["ASA_API_BEARER_TOKEN"]]), "ASA_API_BEARER_TOKEN"))
 
 asa_api_clear_auth_cache()
@@ -240,6 +306,22 @@ expect_error_contains(
 do.call(Sys.setenv, stats::setNames(list(auth_fixture[["GUI_PASSWORD"]]), "GUI_PASSWORD"))
 asa_api_refresh_auth_cache(force = TRUE)
 
+source(file.path(repo_root, "R", "plumber.R"))
+res_env <- new.env(parent = emptyenv())
+rendered_payload <- asa_api_error_payload(
+  res_env,
+  gui_mismatch$status_code,
+  gui_mismatch$message,
+  gui_mismatch$error_code,
+  gui_mismatch$details
+)
+assert_true(
+  identical(res_env$status, 401L) &&
+    identical(rendered_payload$error_code, "credential_mismatch") &&
+    identical(rendered_payload$details$auth_target, "gui_password"),
+  "Route error rendering should preserve structured auth diagnostics."
+)
+
 health_payload <- asa_api_health_payload()
 assert_true(
   identical(isTRUE(health_payload$direct_provider_available), isTRUE(asa_api_has_run_direct_task())),