Skip to content

SDKs

The read-only client for ten languages: what every SDK does, how it opens a vault, the typed errors with hints, and how values are guarded.

9 min read

SourceOrrery ships a read-only client for ten languages. Each one does the same five things and nothing more:

Open a vault by name: this machine’s key in the OS credential store first, then the vault’s recovery key (given in code, SOURCEORRERY_RECOVERY_KEY, or a file, SOURCEORRERY_RECOVERY_KEY_FILE), each source read only if the earlier ones did not open the vault, so a later file that is missing or empty fails only an open that needed it; never an interactive prompt and never the vault’s view check. SOURCEORRERY_HOME says where vaults live.
Get a secret the newest accessible version (enabled, inside its time window) or an explicit version.
Read properties metadata of a version, without policy, so disabled and expired versions can be inspected.
Resolve a reference sourceorrery://vault/name[/version], the form the manifest and the CLI use.
Load a project every secret a sourceorrery.toml declares, resolved like sourceorrery run: required secrets must resolve, optional ones that cannot are left out.

There is no set, update, delete, recover or purge, no key, check or connection management and no audit management in any SDK. Use the CLI to create vaults and set secret values (ADR 0005).

Language Package Technology Guide
Python sourceorrery on PyPI PyO3 + maturin, abi3 wheels (3.11+) Python
JavaScript / TypeScript @sourceorreryai/sdk on npm napi-rs native addon, types included JavaScript
Rust sourceorrery on crates.io the client crate itself Rust
Java ai.sourceorrery:sourceorrery on Maven Central Foreign Function and Memory API (Java 22+) Java
.NET SourceOrrery on NuGet LibraryImport P/Invoke (.NET 8+) .NET
Go github.com/netizine/sourceorrery/bindings/go cgo Go
C sourceorrery.h in the release archive the C ABI C
C++ sourceorrery.hpp in the release archive header-only RAII wrapper C++
PHP sourceorrery/sourceorrery on Packagist the FFI extension PHP

Why each technology: ADR 0006.

Each language page opens with its package registry. The 0.3.1 release publishes to PyPI, npm (under the @sourceorreryai scope), crates.io, Maven Central, NuGet and Packagist, with the Go module on pkg.go.dev. The v0.3.1 GitHub release (opens in a new tab) also carries the packages (wheels, npm tarballs, the jar, the NuGet package) and the C ABI archive that the Go, C, C++ and PHP SDKs load. Use these release files if a registry is still indexing the new version. Each page ends with building that SDK from source; Building from source covers the tools every build needs. How the packages are published and how to check them: Supply chain.

  1. 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.
  2. 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.

Every SDK reads a vault that already exists, so the first steps are the CLI’s:

Terminal window
sourceorrery setup # screens: name, checks, recovery key, storage
sourceorrery secret set database-password --vault development

setup keeps this machine’s key in the OS credential store and hands out the vault’s recovery key once. On a server, in a container or in CI there is no credential store, or not this machine’s: give the process the recovery key in a file.

Terminal window
export SOURCEORRERY_RECOVERY_KEY_FILE=/run/secrets/vault-recovery-key

Provision that file through your environment’s secret-management mechanism and restrict it to the account running the application. Each SDK also accepts a recovery key, a recovery-key file and a home directory in code, for tests and unusual layouts. Avoid putting a recovery key in source code or process arguments; an environment variable containing one can also be inspected by other processes with sufficient privileges. The vault’s view check (a password, perhaps with an authenticator code) is for people browsing the vault; an SDK never asks it.

A vault keeps each secret in its own file or at a provider through one of its connections (providers). The SDK reads such a secret at the provider with the same calls, signing in with the credentials the connection stores, or with the provider’s own chain on the machine (VAULT_TOKEN, the AWS credential chain, an Azure identity); the manifest never names a provider. HashiCorp Vault, AWS Secrets Manager and Azure Key Vault are the providers; a provider the build leaves out fails with unsupported, naming it. Who decides what, and the workload identity set-up per platform: enterprise.md.

Every failure carries the core’s stable error code (opens in a new tab), a message and a hint: one actionable sentence produced by the Rust core, so every language says the same thing.

Code Typed error Hint says
vault_not_found VaultNotFound… how to create the vault with the CLI, and which home directory was searched
locked VaultLocked… which recovery-key sources were tried (option, SOURCEORRERY_RECOVERY_KEY, SOURCEORRERY_RECOVERY_KEY_FILE) and how to give one
migration_required MigrationRequired… the vault was written by an earlier release, which this one cannot read, and its file is left unchanged: keep the file for that release and recreate the vault with this one (Upgrading)
vault_mismatch VaultMismatch… the file found for the vault holds another vault (renamed, copied or swapped in): move it back or restore the vault from a backup, and treat an unexplained swap as tampering
not_found SecretNotFound… how to store the secret (sourceorrery secret set)
version_not_found VersionNotFound… (a SecretNotFound…) list versions, or omit the version
disabled, not_yet_valid, expired SecretDisabled…, SecretNotYetValid…, SecretExpired… (all Policy…) the policy decision and the secret update that changes it; not_yet_valid is marked transient
deleted SecretDeleted… sourceorrery secret recover
crypto Integrity… the file failed an integrity check: compare with a backup, run audit --verify
unsupported Unsupported… no OS credential store here: give the recovery key; or this build has no provider for the one that stores the secret
unauthenticated Unauthenticated… store credentials in the vault’s connection, or where the provider’s own tools take them from (VAULT_TOKEN, the AWS credential chain, an Azure identity)
permission_denied PermissionDenied… the permission the provider’s policy must grant this identity, and the command that shows which identity was refused
provider_unavailable ProviderUnavailable… check that the provider is reachable and the address in the vault’s connection is right; transient, so retry
invalid_argument, invalid_name InvalidArgument…, InvalidName… the reference and name rules
manifest Manifest… fix sourceorrery.toml, check with sourceorrery check
abi_mismatch (Go, Java, .NET, PHP, C++) the base type the native library implements another C ABI version than the SDK was built for: install the sourceorrery-ffi library of the SDK’s release. Raised by the SDK itself before anything is opened, never by the core (ADR 0007)
anything newer the base type, code preserved

Names follow each language’s conventions (SecretNotFoundError in Python, SecretNotFoundException in Java, ErrNotFound sentinel in Go, and so on). No error, message or hint ever contains a secret value.

A value is held in native memory until the application closes it, and the library zeroises it then. The wrapper type prints as [REDACTED], refuses to be serialised where the language allows it, and hands the bytes out only through an explicit call (expose(), Text(), ExposeText()). Once an application copies the bytes out, keeping them safe is the application’s job: a Python str, a Java String or a JavaScript string cannot be wiped, so keep such copies short-lived.

One version number covers the CLI, the crates, the C ABI and every SDK. Before 1.0 a patch release (0.x.y → 0.x.(y+1)) may add but never breaks any of them, so an SDK and the native library it loads may differ by a patch; a minor release may change behaviour and API, and a C ABI change bumps SO_ABI_VERSION, which the bindings check when they load. The rules per surface, and how CI checks them, are in ADR 0007.

Every SDK has a test suite and an example that CI runs on Ubuntu, Windows and macOS against a vault the job creates with the CLI (scripts/ci/fixture-vault.sh: a vault that opens with its recovery key, SOURCEORRERY_RECOVERY_KEY in the environment, secrets covering every policy state, and in the provider jobs secrets kept at the provider through a connection). A binding whose tests do not pass does not ship.

On top of the per-language suites, one conformance harness holds every SDK to the same contract: tests/conformance/sdk/scenarios.json lists the scenarios (unlock sources, latest and explicit versions, references, policy refusals, missing secrets, project loading, with the codes, messages and hints each must produce), each SDK ships a small runner that executes one scenario, and tests/conformance/sdk/harness.py drives a runner through all of them and judges the observations. CI runs it in every SDK job; the protocol and how to add a scenario are in tests/conformance/sdk/README.md (opens in a new tab).

To run them locally, from a clone of the repository with the tools in Building from source, in Bash (Git Bash on Windows):

Terminal window
cargo build --release -p sourceorrery-cli -p sourceorrery-ffi
eval "$(bash scripts/ci/fixture-vault.sh)"
# then, per language, what its page says under "Building from source", and
python tests/conformance/sdk/harness.py --runner python # or rust, node, java, dotnet, go, c, cpp, php

Releases: release.md.