C++
The header-only C++17 wrapper: install the archive from the release or build from source, open a vault, get a secret, catch typed errors, load a project.
A header-only C++17 wrapper, sourceorrery.hpp, over the C ABI.
Project setup options
Section titled “Project setup options”- Option 1: Set up with the CLI. Follow the CLI installation guide, then create the vault and set its secret values in your own terminal.
- Option 2: Set up with an AI coding agent. Run
sourceorrery init --integration all, then ask your agent to set up SourceOrrery for the project without showing values. You keep vault keys and new values private. The agent setup guide works with an existing CLI installation.
Install
Section titled “Install”The C++ SDK is not on a package registry: the release archive is the
package, or build it from source.
sourceorrery.hpp ships next to sourceorrery.h in the include/
directory of the sourceorrery-ffi-0.3.1-<target> archive on the
v0.3.1 release (opens in a new tab),
together with the shared and static libraries. Download the one for your
platform, unpack it, and compile against it exactly as for C;
the example below is get_secret.cpp from the next section.
$release = "https://github.com/Netizine/sourceorrery/releases/download/v0.3.1"$dir = "$env:LOCALAPPDATA\sourceorrery-ffi"Invoke-WebRequest "$release/sourceorrery-ffi-0.3.1-x86_64-pc-windows-msvc.zip" -OutFile sourceorrery-ffi.zip # aarch64-pc-windows-msvc on ArmExpand-Archive sourceorrery-ffi.zip -DestinationPath $dir -Force
cl /std:c++17 /EHsc /I "$dir\include" get_secret.cpp /link "$dir\sourceorrery_ffi.dll.lib"$env:Path = "$dir;$env:Path" # sourceorrery_ffi.dll must be on PATH at run time.\get_secret.exerelease=https://github.com/Netizine/sourceorrery/releases/download/v0.3.1archive=sourceorrery-ffi-0.3.1-aarch64-apple-darwin # x86_64-apple-darwin on Intelcurl -LO "$release/$archive.tar.gz"sudo mkdir -p /opt/sourceorrery && sudo tar xzf "$archive.tar.gz" --no-same-owner -C /opt/sourceorrery --strip-components=1
c++ -std=c++17 -I/opt/sourceorrery/include get_secret.cpp -L/opt/sourceorrery -lsourceorrery_ffi -o get_secretDYLD_LIBRARY_PATH=/opt/sourceorrery ./get_secretrelease=https://github.com/Netizine/sourceorrery/releases/download/v0.3.1archive=sourceorrery-ffi-0.3.1-x86_64-unknown-linux-gnu # aarch64-unknown-linux-gnu on arm64curl -LO "$release/$archive.tar.gz"sudo mkdir -p /opt/sourceorrery && sudo tar xzf "$archive.tar.gz" --no-same-owner -C /opt/sourceorrery --strip-components=1
c++ -std=c++17 -I/opt/sourceorrery/include get_secret.cpp -L/opt/sourceorrery -lsourceorrery_ffi -Wl,-rpath,/opt/sourceorrery -o get_secret./get_secretVerify a download against the release’s SHA256SUMS before unpacking it.
Get a secret
Section titled “Get a secret”#include <sourceorrery.hpp>
int main() { try { auto reader = sourceorrery::Reader::open("development"); auto secret = reader.get("database-password"); connect(secret.value.text()); return 0; // `secret.value` is zeroised here, the reader closed } catch (const sourceorrery::Error& err) { std::cerr << '[' << err.code() << "] " << err.what() << '\n'; // what() = message + hint return 1; }}With the default options, SOURCEORRERY_HOME locates the vault;
this machine’s key in the OS credential store opens it, else the
recovery key: an explicit one, SOURCEORRERY_RECOVERY_KEY, then a file
or SOURCEORRERY_RECOVERY_KEY_FILE. Reader::open(vault, options) takes a
sourceorrery::OpenOptions{home, recovery_key, recovery_key_file, environment} that overrides any of that. The SDK never prompts and never
asks the vault’s view check.
A secret the vault keeps at a provider (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) is read there through the vault’s connection, with the same calls: the connection signs in with the credentials it stores, or with the provider’s own sign-in on the machine. No provider is contacted until a secret it keeps is read.
| Call | Returns |
|---|---|
reader.get(name) |
Secret for the newest accessible version |
reader.get(name, version) |
Secret for exactly that version |
reader.properties_json(name, version) |
the properties document (policy not applied) |
reader.resolve("sourceorrery://development/database-password") |
Secret |
reader.descriptor_json() |
the vault descriptor (no values) |
reader.close() |
releases the vault; the destructor does the same |
Secret holds properties_json (the core’s JSON; version() and name()
read the two most-needed fields, sourceorrery::json_string_field() reads
any other flat string field, or parse it with your JSON library) and
value, a SecretValue: move-only, data() / size() / view() for the
bytes in place, text() for a copy, close() to zeroise early. The
destructor zeroises too.
Errors
Section titled “Errors”Every failure throws sourceorrery::Error (a std::runtime_error) or a
subclass: VaultNotFoundError, VaultLockedError,
MigrationRequiredError, VaultMismatchError, SecretNotFoundError
(also version_not_found), SecretDeletedError, PolicyError
(disabled, not_yet_valid, expired), IntegrityError,
UnsupportedError, InvalidArgumentError (also invalid_name),
ManifestError, UnauthenticatedError (the provider that stores the secret has no
credentials for this process), ProviderUnavailableError (it could not be
reached). Each has code(), message(), hint(), kind(),
transient() (true for not_yet_valid and provider_unavailable) and
policy(). See the SDK overview.
Load a project
Section titled “Load a project”auto project = sourceorrery::Project::load("sourceorrery.toml"); // std::nullopt discovers itfor (const auto& secret : project.secrets()) { setenv(secret.env.c_str(), secret.value.text().c_str(), 1);}project.close(); // zeroise every valueBuilding from source
Section titled “Building from source”You need Git, Rust 1.91.1 or newer installed with rustup, and a C compiler
(on Linux also pkg-config and libdbus-1-dev);
Building from source has the commands for
each platform. For this SDK, also a C++17 compiler, and CMake 3.16 or
newer to build the example and the test.
The wrapper is a header; what you build is the C ABI library under it:
git clone https://github.com/Netizine/sourceorrerycd sourceorrerygit checkout v0.3.1 # or stay on main for the newest changescargo build --release -p sourceorrery-ffiCompile against bindings/cpp/include (for sourceorrery.hpp),
crates/sourceorrery-ffi/include (for sourceorrery.h, which it
includes) and the library in target/release, where the install steps
above use the unpacked archive. In CMake, bindings/cpp/CMakeLists.txt
defines an interface target, sourceorrery, that carries all three.
To build and run the example, the test and the conformance runner against the test vault the CLI creates, build the CLI too and run the rest in Bash from the repository root:
cargo build --release -p sourceorrery-cli -p sourceorrery-ffieval "$(bash scripts/ci/fixture-vault.sh)" # a throwaway vault, the variables the tests read, SOURCEORRERY_NATIVE_DIRcmake -S bindings/cpp -B build/cpp -DSOURCEORRERY_NATIVE_DIR="$SOURCEORRERY_NATIVE_DIR"cmake --build build/cpp --config Release # get_secret and reader_testc++ -std=c++17 -Wall -Wextra -Werror -I bindings/cpp/include -I crates/sourceorrery-ffi/include \ bindings/cpp/conformance/run.cpp -L "$SOURCEORRERY_NATIVE_DIR" -lsourceorrery_ffi -o build/conformance_cppexport LD_LIBRARY_PATH="$SOURCEORRERY_NATIVE_DIR" DYLD_LIBRARY_PATH="$SOURCEORRERY_NATIVE_DIR"ctest --test-dir build/cpp -C Release --output-on-failurebuild/cpp/get_secret "$SOURCEORRERY_TEST_VAULT" database-passwordpython tests/conformance/sdk/harness.py --runner cppOn Windows, run this in Git Bash started from a Developer Command Prompt
for VS, so that MSVC’s cl is on PATH, as described for
C. CMake builds into build/cpp/Release/
there; compile the runner with
cl -nologo -std:c++17 -EHsc -W4 -WX -I bindings/cpp/include -I crates/sourceorrery-ffi/include bindings/cpp/conformance/run.cpp -Fe:build/conformance_cpp.exe -Fo:build/ -link "$SOURCEORRERY_NATIVE_DIR/sourceorrery_ffi.dll.lib"
and put the DLL on PATH with
export PATH="$(cygpath -u "$SOURCEORRERY_NATIVE_DIR"):$PATH".
CI compiles everything with -Wall -Wextra -Werror (gcc, clang) and
/W4 /WX (MSVC). What the fixture script creates:
The SDK test vault.
Source: bindings/cpp (opens in a new tab).