auth functions

[ijlyttle]

Gotta start somewhere - looking over the httr2 Wrapping APIs article, I see code like this:

library("httr2")

request("https://api.github.com/user") %>% 
  req_oauth_auth_code(client, auth_url = "https://github.com/login/oauth/authorize") %>% 
  req_perform() %>% 
  resp_body_json()

For us, I think it could be useful to think of auth as a function you create, so we might suggest something like this:

library("httr2")
library("cardboard")

# use interactive login
req_auth <- bx_auth_create_interactive(id, secret, .test = TRUE) 

request("https://api.box.com/2.0/users/me") %>%
  req_auth() %>%
  req_perform() %>% 
  resp_body_json()

We would need a family of functions:

# if auth is:
#  - cardborad_function: no-op
#  - character: consult keyring
#  - list: parse
#  - NULL: consult keyring, return if only one candidiate
bx_auth_get(auth = NULL)

# sets default using `bx_auth_get()`
bx_auth_use(auth = NULL, quiet = FALSE) 

# returns default auth
bx_auth()

# these return auth functions
bx_auth_create_interactive(id, secret, cache_disk = FALSE, .test = TRUE)
bx_auth_create_credentials(id, secret, subject_type, subject_id, cache_disk = FALSE, .test = TRUE)
 
# returns list with elements `type`, `params`
bx_auth_serialize(auth) # can be function or character (keyring name)
bx_auth_parse(type = c("interactive", "credentials"), params) # returns auth function

# returns logical, invisibly
bx_auth_test(auth, quiet = FALSE)  # can be function or character (keyring name)

# returns NULL, invisibly
bx_auth_inspect(auth)  # can be function or character (keyring name)

also

# sets auth in package environment
bx_auth_use(auth = NULL, .test = TRUE) # can be function or character (keyring name), NULL means use only name

# if key is NULL, use internal function to generate then print to screen
bx_auth_encrypt(auth, file, key = NULL, nonce = NULL)
bx_auth_decrypt(file, key, nonce = NULL, .test = TRUE)

• bx_auth_get()
• bx_auth_create_interactive()
• bx_auth_create_credentials()
• bx_auth_test()
• bx_auth_serialize()
• bx_auth_parse()
• bx_auth_inspect()
• bx_auth_use()
• bx_auth()
• bx_auth_encrypt()
• bx_auth_decrypt()

Don't forget

• set up testing
• document everything