Go SDK

The Go SDK (monosecret_go) is a thin client over the monosecret_ffi C ABI, loaded via purego (dlopen, no cgo). Resolution happens in the Rust core, so the SDK inherits every provider with no Go-side logic.

Quick start

package main

import (
	"fmt"
	"log"

	monosecret "github.com/ifiokjr/monosecret/go/monosecret_go"
)

func main() {
	resolved, err := monosecret.New().
		WithProvider("keyring://").
		WithProfile("production").
		WithReason("boot web app").
		Load()

	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(resolved.Provider, resolved.Profile)
	db := resolved.Secrets["DATABASE_URL"]
	fmt.Println(db.Get()) // the value, or the file path for as_path secrets
	resolved.SetAsEnv()   // export everything into the process environment
}

A missing required secret returns *MissingRequiredError; any other failure returns *Error (with a stable .Kind).

Caller context

Version compatibility

Added in Monosecret 0.3.

builder := monosecret.New().WithCaller(monosecret.CallerContext{
    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

Version compatibility

Added in Monosecret 0.3.

Applications that own their declarations in code can resolve a strict JSON inline specification without creating a temporary monosecret.toml file. Pass the wire document to WithInlineSpec; baseDir resolves relative provider paths just as a manifest’s directory would. The current SDK sends inline schema v2, which requires Monosecret 0.4.0+.

spec := map[string]any{
    "project": map[string]any{"name": "my-app"},
    "profiles": map[string]any{
        "default": map[string]any{"secrets": map[string]any{
            "API_TOKEN": map[string]any{"description": "API token"},
        }},
    },
}
resolved, err := monosecret.New().
    WithInlineSpec(spec, "/logical/project").
    WithReason("application startup").
    Load()

Inline specification v2 (Monosecret 0.4.0+) uses project, profiles, and each profile’s secrets object; optional providers, scopes, project defaults, profile defaults, and the normal secret declaration fields are also supported. A 0.4.0+ library still accepts the v1 documents sent by earlier SDKs. Unknown declaration fields are rejected. project.extends resolves parent manifests relative to baseDir. The SDK requires the native monosecret_call capability for inline specs; an older library returns a capability error rather than falling back to a filesystem search.

Scopes (0.3+)

Use WithScope("api") to resolve only a named [scopes.api] subset. The selected name is available as Resolved.Scope and Report.Scope:

package main

import (
	"log"

	monosecret "github.com/ifiokjr/monosecret/go/monosecret_go"
)

func main() {
	resolved, err := monosecret.New().WithScope("api").Load()
	if err != nil {
		log.Fatal(err)
	}

	defer resolved.Close()
}

Typed access (codegen)

Generate typed structs with monosecret schema plus quicktype, then unmarshal resolved.FieldsJSON():

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

package main

import (
	"fmt"
	"log"

	monosecret "github.com/ifiokjr/monosecret/go/monosecret_go"
)

func main() {
	resolved, err := monosecret.New().Load()
	if err != nil {
		log.Fatal(err)
	}

	defer resolved.Close()

	data, _ := resolved.FieldsJSON()
	typed, _ := UnmarshalMonosecret(data) // typed, generated
	fmt.Println(typed.DatabaseURL)
}

Library discovery

The native monosecret_ffi cdylib is resolved at runtime, in order:

1. The MONOSECRET_FFI_LIB environment variable (an explicit path).
2. A library embedded at build time with -tags embed_lib.
3. A Cargo target directory found by searching up from the working directory (the development path).

The SDK uses purego, so the cdylib is loaded at runtime, not linked. Either install/build monosecret_ffi and set MONOSECRET_FFI_LIB, or stage the per-platform library into lib/ and build with -tags embed_lib for a self-contained binary. The embedded library is extracted to a per-user, owner-only cache directory at first use, and is not distributed through the Go module proxy.

Static linking

For a self-contained binary with no runtime library to locate, build with -tags static instead. This uses cgo and links libmonosecret_ffi.a directly into the Go binary. In a development checkout:

$ bash scripts/stage-staticlib.sh

$ CGO_ENABLED=1 go build -tags static ./...

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 build command for either type:

$ PKG_CONFIG_PATH="$PREFIX/lib/pkgconfig" CGO_ENABLED=1 go build -tags pkgconfig ./...

Unlike staging, this also works for a go get dependency. A shared install in a non-system prefix also requires PREFIX/lib in the platform’s runtime library search path.