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.
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.
Installing
Section titled “Installing”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.
Setting up
Section titled “Setting up”Setup choices
Section titled “Setup choices”- 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.
Every SDK reads a vault that already exists, so the first steps are the CLI’s:
sourceorrery setup # screens: name, checks, recovery key, storagesourceorrery secret set database-password --vault developmentsetup 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.
export SOURCEORRERY_RECOVERY_KEY_FILE=/run/secrets/vault-recovery-keyProvision 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.
Secrets kept at a provider
Section titled “Secrets kept at a provider”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.
Errors
Section titled “Errors”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.
Values
Section titled “Values”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.
Compatibility
Section titled “Compatibility”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.
How the SDKs are tested
Section titled “How the SDKs are tested”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):
cargo build --release -p sourceorrery-cli -p sourceorrery-ffieval "$(bash scripts/ci/fixture-vault.sh)"# then, per language, what its page says under "Building from source", andpython tests/conformance/sdk/harness.py --runner python # or rust, node, java, dotnet, go, c, cpp, phpReleases: release.md.