Package {googlesecretmanager}

As Secret

Description

As Secret

Usage

as_secret(x, ...)

Arguments

Value

An sm_secret object. The method invoked depends on the class of x; see as_secret.character() for the supported input.

As Secret Character

Description

As Secret Character

Usage

## S3 method for class 'character'
as_secret(x, ...)

Arguments

Value

An sm_secret object: a list with class c("sm_secret", "list") containing the parsed secret metadata.

Print sm_secret

Description

Print sm_secret

Usage

## S3 method for class 'sm_secret'
print(x, ...)

Arguments

Value

The sm_secret object x, invisibly. Called for its side effect of printing a summary of the secret's metadata; the secret's value is never displayed.

Print sm_tbl

Description

Print sm_tbl

Usage

## S3 method for class 'sm_tbl'
print(x, ...)

Arguments

Value

The sm_tbl object x, invisibly. Called for its side effect of printing a summary of the underlying data frame.

Retrieve the configured API key

Description

Returns the currently configured API key for the googlesecretmanager package. Note: API keys have limited use with Secret Manager, which primarily relies on OAuth2.0.

Usage

sm_api_key()

Value

A string containing the API key, or NULL if no key is configured.

Examples

## Not run: 
# Configure API key first (if applicable)
# sm_auth_configure(api_key = "YOUR_API_KEY")
key <- sm_api_key()
if (!is.null(key)) {
  print(key)
}

## End(Not run)

Authenticate with Google Secret Manager

Description

This function handles authentication with Google Cloud Secret Manager. It's called automatically when the first token is needed, or it can be called directly by the user to pre-authenticate or to switch identities, scopes, or authentication methods (e.g., user OAuth, service account token).

Following gargle best practices for sensitive APIs, googlesecretmanager does not come with a built-in OAuth client or API key. You must configure your own via sm_auth_configure() or provide a service account token via the path argument.

Usage

sm_auth(
  email = gargle::gargle_oauth_email(),
  path = NULL,
  scopes = "https://www.googleapis.com/auth/secretmanager",
  cache = gargle::gargle_oauth_cache(),
  use_oob = gargle::gargle_oob_default(),
  token = NULL
)

Arguments

Value

Invisibly returns NULL. The main effect is to configure authentication state for the package.

Examples

## Not run: 
# To configure your own OAuth client (do this once per project/user):
sm_auth_configure(
 path = "/path/to/your/oauth-client-secret.json"
)

# Authenticate (often not needed explicitly, called by API functions):
sm_auth()

# Authenticate with a specific user:
sm_auth(email = "my_user@example.com")

# Authenticate using a service account:
sm_auth(path = "/path/to/your/service-account-key.json")

# Authenticate using a pre-fetched token (like googleCloudStorageR example):
token <- gargle::token_fetch(
  scopes = "https://www.googleapis.com/auth/cloud-platform"
)
sm_auth(token = token)

## End(Not run)

Configure OAuth client and API key for Secret Manager

Description

This function allows advanced users to provide their own OAuth client ID and secret (from a JSON file downloaded from Google Cloud Console) or an API key.

OAuth Client: For googlesecretmanager, providing your own OAuth client is highly recommended as the package does not ship with a default client due to the sensitive nature of the API.

API Key: While the gargle framework supports API keys, most Secret Manager operations require OAuth2.0 authentication. An API key might be useful for very limited, typically read-only, public data scenarios, which are rare for Secret Manager. It's included for structural consistency with gargle but may have limited direct use for this package.

Usage

sm_auth_configure(path = NULL, client = NULL, api_key = NULL, app = NULL)

Arguments

Value

Invisibly returns the updated auth configuration (an AuthState object).

Examples

## Not run: 
# Configure with an OAuth client downloaded from GCP
sm_auth_configure(
  path = "/path/to/your/oauth-client-secret.json"
)

# To configure with an API key (less common for Secret Manager):
# sm_auth_configure(api_key = "YOUR_API_KEY")

# Check configured client:
sm_oauth_client()

## End(Not run)

De-authenticate from Secret Manager

Description

Clears the current Secret Manager token. This means the next API request that requires authentication will trigger the authentication process anew (e.g., by calling sm_auth()).

Since Secret Manager generally requires authentication for all its significant operations (and doesn't typically use API keys for accessing secrets), de-authentication primarily serves to clear the current user's session or force a re-authentication.

Usage

sm_deauth()

Value

Invisibly returns NULL.

Examples

## Not run: 
sm_deauth()
# Next API call will re-trigger auth
# list_secrets() # (Assuming this is a function in your package)

## End(Not run)

Secret Manager Endpoint

Description

Secret Manager Endpoint

Usage

sm_endpoint(i)

Arguments

Value

A single Secret Manager API endpoint: a named list with elements such as id, httpMethod, path, parameters, scopes, and response.

List Secret Manager endpoints

Description

The googlesecretmanager package stores a named list of Secret Manager API v1 endpoints (or "methods", using Google's vocabulary) internally and these functions expose this data.

• sm_endpoint() returns one endpoint, i.e. it uses [[.

• sm_endpoints() returns a list of endpoints, i.e. it uses [.

The names of this list (or the id sub-elements) are the nicknames that can be used to specify an endpoint in request_generate(). For each endpoint, we store its nickname or id, the associated HTTP verb, the path, and details about the parameters. This list is derived programmatically from the Secret Manager API v1 Discovery Document (⁠https://www.googleapis.com/discovery/v1/apis/secretmanager/v1/rest⁠) using the approach described in the Discovery Documents section of the gargle vignette Request helper functions.

Usage

sm_endpoints(i = NULL)

Arguments

Value

One or more of the Secret Manager API v1 endpoints that are used internally by googlesecretmanager.

Examples

str(head(sm_endpoints(), 3), max.level = 2)
sm_endpoint("secretmanager.projects.secrets.versions.destroy")
sm_endpoint(4)

Check if a token is available

Description

Checks if a token is present in the internal authentication state. This is an internal helper function.

Usage

sm_has_token()

Value

Logical. TRUE if a token is available, FALSE otherwise.

Retrieve the configured OAuth client

Description

Returns the currently configured OAuth client for the googlesecretmanager package. This client is used in the OAuth flow to obtain tokens. By default, this will be NULL until configured by the user via sm_auth_configure().

Usage

sm_oauth_client()

Value

A gargle_oauth_client object, or NULL if no client is configured.

Examples

## Not run: 
# Configure client first
# sm_auth_configure(path = "/path/to/your/client.json")
client <- sm_oauth_client()
if (!is.null(client)) {
  print(client)
}

## End(Not run)

Set Default Google Cloud Project ID

Description

Sets the default Google Cloud Project ID for subsequent Secret Manager operations within the current R session. Functions will automatically use this project ID unless explicitly overridden.

Usage

sm_project_set(project_id)

Arguments

Value

The project_id character string, invisibly. Called for its side-effect of setting the default project.

Examples

## Not run: 
sm_project_set("my-production-project")
# Now, sm_secret_ls() will default to "my-production-project"

sm_project_get() # "my-production-project"

# You can always override the default for specific calls:
sm_secret_get("my-secret", project_id = "another-project")

## End(Not run)

Create a Secret

Description

Creates a new Secret containing no SecretVersions.

Usage

sm_secret_create(
  secret_id,
  project_id = sm_project_get(),
  replication = list(automatic = list()),
  labels = NULL,
  ...
)

Arguments

Value

An sm_secret object representing the created secret.

Delete a Secret

Description

Deletes a Secret and all of its versions.

Usage

sm_secret_delete(secret, project_id = sm_project_get(), ...)

## S3 method for class 'character'
sm_secret_delete(secret, project_id = sm_project_get(), ...)

## S3 method for class 'sm_secret'
sm_secret_delete(secret, project_id = sm_project_get(), ...)

Arguments

Value

Invisibly returns NULL.

Get Secret Metadata

Description

Retrieves metadata for a specific Secret Manager secret.

Usage

sm_secret_get(x, project_id = sm_project_get(), ...)

## S3 method for class 'character'
sm_secret_get(x, project_id = sm_project_get(), ...)

## S3 method for class 'sm_secret'
sm_secret_get(x, project_id = sm_project_get(), ...)

Arguments

Value

An sm_secret object: a list with class c("sm_secret", "list") containing the secret's name, secret_id, project_id, location_id, metadata such as createTime, labels, and etag, and the raw API response in raw_api_response.

List Secrets in a Project

Description

Lists metadata for all Secrets in a given Google Cloud Project.

Usage

sm_secret_ls(project_id = sm_project_get(), filter = NULL, ...)

Arguments

Value

An sm_tbl object, a data frame with class c("sm_tbl", "tbl_df", "tbl", "data.frame") and one row per secret. Columns are secret_id, project_id, name, createTime, labels (a list-column), and etag. An empty sm_tbl is returned when the project contains no secrets.

List Secrets in a Project

Description

Lists metadata for all Secrets in a given Google Cloud Project.

Usage

## S3 method for class 'character'
sm_secret_ls(project_id = sm_project_get(), filter = NULL, ...)

Arguments

Value

An sm_tbl object, a data frame with class c("sm_tbl", "tbl_df", "tbl", "data.frame") and one row per secret. Columns are secret_id, project_id, name, createTime, labels (a list-column), and etag. An empty sm_tbl is returned when the project contains no secrets.

Update a Secret

Description

Updates metadata of an existing Secret.

Usage

sm_secret_update(
  secret,
  project_id = sm_project_get(),
  replication = NULL,
  labels = NULL,
  etag = NULL,
  ...
)

## S3 method for class 'character'
sm_secret_update(
  secret,
  project_id = sm_project_get(),
  replication = NULL,
  labels = NULL,
  etag = NULL,
  ...
)

## S3 method for class 'sm_secret'
sm_secret_update(
  secret,
  project_id = sm_project_get(),
  replication = NULL,
  labels = NULL,
  etag = NULL,
  ...
)

Arguments

Value

An sm_secret object representing the updated secret.

Access a Secret Version's Value

Description

Accesses and decrypts the secret data stored in a specific Secret Version. Unlike sm_secret_version_get(), which returns version metadata, this function returns the actual secret value.

Usage

sm_secret_version_access(
  secret,
  version_id = "latest",
  project_id = sm_project_get(),
  ...
)

## S3 method for class 'character'
sm_secret_version_access(
  secret,
  version_id = "latest",
  project_id = sm_project_get(),
  ...
)

## S3 method for class 'sm_secret'
sm_secret_version_access(
  secret,
  version_id = "latest",
  project_id = sm_project_get(),
  ...
)

Arguments

Value

A length-one character vector containing the decoded secret value. The data_crc32c checksum returned by the API is attached as an attribute.

Add a Secret Version

Description

Adds a new version to an existing Secret.

Usage

sm_secret_version_add(secret, payload, project_id = sm_project_get(), ...)

## S3 method for class 'character'
sm_secret_version_add(secret, payload, project_id = sm_project_get(), ...)

## S3 method for class 'sm_secret'
sm_secret_version_add(secret, payload, project_id = sm_project_get(), ...)

Arguments

Value

An sm_secret_version object representing the new version.

Delete a Secret Version

Description

Deletes a Secret Version.

Usage

sm_secret_version_delete(
  secret,
  version_id,
  project_id = sm_project_get(),
  ...
)

## S3 method for class 'character'
sm_secret_version_delete(
  secret,
  version_id,
  project_id = sm_project_get(),
  ...
)

## S3 method for class 'sm_secret'
sm_secret_version_delete(
  secret,
  version_id,
  project_id = sm_project_get(),
  ...
)

Arguments

Value

Invisibly returns NULL.

Disable a Secret Version

Description

Disables a Secret Version.

Usage

sm_secret_version_disable(
  secret,
  version_id,
  project_id = sm_project_get(),
  ...
)

## S3 method for class 'character'
sm_secret_version_disable(
  secret,
  version_id,
  project_id = sm_project_get(),
  ...
)

## S3 method for class 'sm_secret'
sm_secret_version_disable(
  secret,
  version_id,
  project_id = sm_project_get(),
  ...
)

Arguments

Value

An sm_secret_version object representing the disabled version.

Enable a Secret Version

Description

Enables a Secret Version.

Usage

sm_secret_version_enable(
  secret,
  version_id,
  project_id = sm_project_get(),
  ...
)

## S3 method for class 'character'
sm_secret_version_enable(
  secret,
  version_id,
  project_id = sm_project_get(),
  ...
)

## S3 method for class 'sm_secret'
sm_secret_version_enable(
  secret,
  version_id,
  project_id = sm_project_get(),
  ...
)

Arguments

Value

An sm_secret_version object representing the enabled version.

Get Secret Version Metadata

Description

Gets metadata for a specific Secret Version.

Usage

sm_secret_version_get(secret, version_id, project_id = sm_project_get(), ...)

## S3 method for class 'character'
sm_secret_version_get(secret, version_id, project_id = sm_project_get(), ...)

## S3 method for class 'sm_secret'
sm_secret_version_get(secret, version_id, project_id = sm_project_get(), ...)

Arguments

Value

An sm_secret_version object representing the version metadata.

List Secret Versions

Description

Lists metadata for all Secret Versions associated with a given Secret.

Usage

sm_secret_version_ls(secret, project_id = sm_project_get(), filter = NULL, ...)

## S3 method for class 'sm_secret'
sm_secret_version_ls(secret, project_id = sm_project_get(), filter = NULL, ...)

## S3 method for class 'character'
sm_secret_version_ls(secret, project_id = sm_project_get(), filter = NULL, ...)

Arguments

Value

An sm_tbl object, a data frame with class c("sm_tbl", "tbl_df", "tbl", "data.frame") and one row per secret version. Columns are secret_id, version_id, name, createTime, state, and etag. An empty sm_tbl is returned when the secret has no versions.

Provide a token for Secret Manager API requests

Description

Retrieves the current token for Secret Manager. If authentication is active (.sm_auth$auth_active is TRUE) and no token is cached, it will trigger sm_auth() to obtain one.

This function is typically used by other package functions that make API requests.

Usage

sm_token()

Value

An httr::config object containing the httr::Token2.0 object, or NULL if auth is inactive.

Examples

## Not run: 
# Configure auth first if needed (e.g., with your client ID)
# sm_auth_configure(path = "path/to/client.json")
# sm_auth() # or let it be called automatically

token <- sm_token()
if (!is.null(token)) {
  # Use token in httr::GET() or other API calls
}

## End(Not run)

Get information about the authenticated user

Description

Provides information about the Google identity associated with the current token. This usually includes the email address. It attempts to retrieve this information from the token itself.

Usage

sm_user(token = NULL)

Arguments

Value

A list containing user information (e.g., email) or NULL if no token is available or user information cannot be parsed.

Examples

## Not run: 
# Authenticate first
# sm_auth()

user_info <- sm_user()
if (!is.null(user_info)) {
  print(user_info$email)
}

## End(Not run)