Node API

`SecRefs`

import { SecRefs, secRefs } from "@secrefs/node";

secRefs is a ready-made singleton using the default providers. Construct your own when you need custom aliases.

Method	Returns	Notes
`init()`	`string[]`	Expands `process.env` in place; returns the keys rewritten
`expandEnv(map)`	`Record<string,string>`	Expands an arbitrary map, leaving `process.env` alone
`expandString(value)`	`string`	Resolves one reference; a plain value passes through unchanged
`check(env?)`	`CheckResult[]`	Validates without ever returning a value

new SecRefs({
  providers,      // ProviderRegistry - defaults to the four built-ins
  strict: true,   // throw on a malformed reference (default)
})

Errors

A failed fetch throws SecretFetchError, which classifies the cause:

import { SecretFetchError } from "@secrefs/node";

try {
  await secRefs.expandString(ref);
} catch (err) {
  if (err instanceof SecretFetchError) {
    err.kind;    // "auth" | "not_found" | "denied" | "transient" | "unknown"
    err.remedy;  // e.g. "Run: aws sso login --profile prod" (auth only)
  }
}

kind is what lets a caller retry a transient fault without also retrying a dead credential forever. Expanding a map throws SecRefsResolutionError, aggregating every failure. Its isAuthOnly getter distinguishes “your credentials lapsed” from “your references are wrong”.

Providers

import {
  AwsSecretsManagerProvider,
  BitwardenProvider,
  VaultProvider,
  LocalProvider,
} from "@secrefs/node";

Each takes options documented on its own page. All accept cacheTtlMs and staleGraceMs — see Load time vs use time.

Custom providers

Implement ISecretProvider (or extend BaseSecretProvider, which gives you concurrent batching for free) and register it under any alias:

class MyProvider extends BaseSecretProvider {
  readonly name = "mine";
  async fetchOne({ path, field }) { /* ... */ }
  async healthCheck() { return { provider: this.name, ok: true }; }
}

new SecRefs({ providers: { mine: new MyProvider() } });
// sec://mine/whatever#field

Getting started

Providers

Guides

Reference

`SecRefs`

Errors

Providers

Custom providers

​SecRefs

​Errors

​Providers

​Custom providers

`SecRefs`

Errors

Providers

Custom providers