Skip to content

README.md

Latest commit

 

History

History
107 lines (81 loc) · 4.59 KB

README.md

File metadata and controls

107 lines (81 loc) · 4.59 KB
Raw

Node.js SDK

Node.js SDK for Keyorix — lightweight on-premise secrets manager.

Zero external dependencies. Uses Node.js built-in http/https modules.

Install

npm install @keyorixhq/sdk

Quick start

const keyorix = require('@keyorixhq/sdk');

// Recommended for apps: a machine identity token, not a user password.
// Issue one via `keyorix machine token issue <name|id>` (or the web
// UI's Project -> Machine Identities -> Issue Token), then load it
// from your app's secret store / env var -- never hardcode it.
const client = new keyorix.Client('https://your-server:8443', process.env.KEYORIX_TOKEN);

// A personal access token (PAT) works exactly the same way -- pass it
// as the token above. Password login (below) is for humans at a
// terminal, not for baking into an application.
//
//   const token = await keyorix.login('https://your-server:8443', 'admin', 'your-password');
//   const client = new keyorix.Client('https://your-server:8443', token);

// Get a secret value, identified entirely by name -- one round trip,
// resolved and authorized server-side. No project/environment-list
// permission required, so this is the shape that works for a machine
// token scoped to exactly one project.
const dbPassword = await client.getSecretIn('my-project', 'production', 'db-password');

// Already have (or want to cache) project/environment IDs instead of
// names? Use the *Scoped methods.
const secrets = await client.listSecretsScoped('my-project', 'production');
secrets.forEach(s => console.log(s.name, s.type));

Environment variables pattern

const client = new keyorix.Client(
  process.env.KEYORIX_SERVER,
  process.env.KEYORIX_TOKEN
);
const dbPassword = await client.getSecretIn('my-project', 'production', 'db-password');

API

  • new keyorix.Client(serverUrl, token, opts?) — token is a machine identity token, a PAT, or a session token; the server accepts all three identically. For an app running unattended, prefer a machine identity token over a user's password.
  • keyorix.login(serverUrl, username, password) -> Promise — authenticates with a human's username/password. For interactive use, not for an application's long-running credential.
  • client.getSecretIn(project, environment, name) -> Promise — a single server-authorized round trip (GET /api/v1/secrets/value?ref=project/environment/name). Needs no project/environment-list permission, unlike getSecretScoped.
  • client.getSecretByRef(ref) -> Promise — same as getSecretIn, but takes one "project/environment/name" string (the name may itself contain /) instead of three arguments. getSecretIn is a thin wrapper around this.
  • client.getSecretScoped(name, project, environment) -> Promise — prefer getSecretIn unless you already have (or want to cache) project/environment IDs: this costs up to two extra round trips to resolve a name-based project/environment the first time, and needs project/environment-list permission to do so.
  • client.listSecretsScoped(project, environment) -> Promise<Secret[]> — follows every page the server reports.
  • client.health() -> Promise

project/environment each accept either a name (string, resolved to an ID via the server and cached on the Client for its lifetime) or a numeric ID (number, no resolution round trip).

getSecretScoped matches name exactly among the secrets in that scope: zero matches throws SecretNotFoundError, more than one throws AmbiguousSecretError (with .ids listing every match) — it never guesses.

Deprecated: getSecret/listSecrets (environment-only)

Removed in v0.3.0. An environment name is only unique within one project, not globally, so scoping by environment alone could silently resolve to another project's same-named secret. These now always throw without contacting the server — use getSecretScoped/listSecretsScoped instead.

Errors

  • KeyorixError — base
  • AuthError — authentication failure
  • SecretNotFoundError — secret not found
  • AmbiguousSecretError — secret name matched more than one secret in scope (.ids)

Requirements

Node.js 18+, zero external dependencies, Keyorix server v0.1.0+

Compatibility

See ../COMPATIBILITY.md for the current known-compatible server versions and per-endpoint coverage — verified by ../.github/workflows/contract.yml against a real keyorix-server, not asserted by hand.

License

Apache-2.0 — see the repository root LICENSE