Node.js SDK

The Node.js / TypeScript SDK (monosecret) is a thin wrapper over a napi-rs native addon that embeds the resolver. Resolution happens in the Rust core, so the SDK inherits every provider with no JS-side logic. npm installs a prebuilt addon for the host platform: Linux x64 and arm64 (glibc, and musl for Alpine images in 0.20+), macOS on Apple silicon, and Windows x64. TypeScript declarations ship in index.d.ts.

Quick start

const { Monosecret } = require("monosecret");

const resolved = Monosecret.builder()
  .withProvider("keyring://")
  .withProfile("production")
  .withReason("boot web app")
  .load();

console.log(resolved.provider, resolved.profile);
const db = resolved.secrets.DATABASE_URL;
console.log(db.get()); // the value, or the file path for as_path secrets
resolved.setAsEnv(); // export everything into process.env

A missing required secret throws MissingRequiredError; any other failure throws MonosecretError (with a stable .kind).

Caller context

const builder = Monosecret.builder().withCaller({
  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 .withInlineSpec(spec, baseDir) (or loadAsync/reportAsync) to resolve a strict inline-spec v1 object. baseDir resolves relative provider paths; the embedded addon submits the versioned native request directly.

Scopes (0.2+)

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

const resolved = Monosecret.builder().withScope("api").load();

Typed access (codegen)

Generate typed interfaces with monosecret schema plus quicktype, then convert resolved.fieldsJson():

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

import { Convert } from "./secrets_gen"; // typed, generated

const typed = Convert.toMonosecret(resolved.fieldsJson());
console.log(typed.DATABASE_URL);