Ruby SDK

Quick start

require "monosecret"

resolved = Monosecret.builder
                                 .with_provider("keyring://")
                                 .with_profile("production")
                                 .with_reason("boot web app")
                                 .load

puts resolved.provider, resolved.profile
db = resolved.secrets["DATABASE_URL"]
puts db.get             # the value, or the file path for as_path secrets
resolved.set_as_env!    # export everything into ENV

A missing required secret raises Monosecret::MissingRequiredError; any other failure raises Monosecret::Error (with a stable #kind).

Caller context

builder = Monosecret::Monosecret.builder.with_caller(
  Monosecret::CallerContext.new(
    name: "git",
    version: "2.51.0",
    operation: "credential_get",
    resource: "github.com"
  )
)

Caller context identifies the invoking integration in audit records but never satisfies require_reason. Do not put credentials or secret values in it.

Inline specifications

Use .with_inline_spec(spec, base_dir) to resolve a strict inline-spec v1 hash at its logical provider-path base directory. The extension links the separate native call symbol, so an older archive cannot fall back to a manifest search.

Scopes (0.2+)

Use .with_scope("api") to resolve only a named [scopes.api] subset. The selected name is available as resolved.scope and report.scope:

resolved = Monosecret.builder.with_scope("api").load

Typed access (codegen)

Generate typed classes with monosecret schema plus quicktype, then build them from resolved.fields:

$ monosecret schema | quicktype -s schema --top-level Monosecret --lang ruby -o secrets_gen.rb

typed = Monosecret.from_dynamic!(resolved.fields) # typed, generated
puts typed.database_url

Native library

The published platform gems bundle the monosecret_ffi archive and statically link it into the mkmf extension at install time.

Linking with pkg-config (0.2+)

Install one library type with cargo-c:

# Use "static" (the default) or "shared"; use separate prefixes for both.
$ bash monosecret_ffi/scripts/cinstall.sh "$PREFIX" static

Then use the same extension flag for either type:

$ PKG_CONFIG_PATH="$PREFIX/lib/pkgconfig" gem install monosecret -- --enable-pkg-config

A shared install in a non-system prefix also requires PREFIX/lib in the platform’s runtime library search path.