Load secrets in Node and NestJS
Two npm packages let a service read its configuration from Anchor, without wrapping the process
in anchor run:
@anchor-secrets/sdk: a small Node client (Node 20 or later, no runtime dependencies).@anchor-secrets/nestjs: a NestJS module built on it (NestJS 10, 11 or 12).
Both cache what they fetch, so reading a value does not call Anchor each time. A read of values
older than the cache ttl (one minute by default) starts one background refresh; there is no timer,
so an idle service asks nothing. A refresh is a conditional request: when nothing changed, Anchor
answers 304 and the service keeps the values it has. When Anchor is unreachable, a running
service keeps its values too. They only read; writing secrets stays with the CLI and the
dashboard.
Give the service a token
Section titled “Give the service a token”Create a read service token scoped to the environment (and, if you like, the folder) the service
needs:
anchor tokens create --name zepo-engine-prod --scope prod:/shared --permission read --project zepoGive the service two variables, through your platform’s secret settings:
ANCHOR_API_URL=https://anchor.example.comANCHOR_TOKEN=anc_st_...A token expires after 90 days by default. For a long-running server you can create one with
--expires-in never; see Tokens without an expiry.
Every request that returns values is in the project’s audit log under the token’s name. A refresh
answered with 304 returns no values and writes no audit row, so an unchanged folder adds nothing
to the log.
NestJS
Section titled “NestJS”npm install @anchor-secrets/nestjsimport { Module } from "@nestjs/common";import { AnchorModule } from "@anchor-secrets/nestjs";
@Module({ imports: [AnchorModule.forRoot({ project: "zepo", environment: "prod", path: "/shared" })],})export class AppModule {}import { Injectable } from "@nestjs/common";import { AnchorService } from "@anchor-secrets/nestjs";
@Injectable()export class DatabaseService { constructor(private readonly anchor: AnchorService) {}
connectionString(): string { return this.anchor.getOrThrow<string>("DATABASE_URL"); }
poolSize(): number { return this.anchor.get<number>("DB_POOL_SIZE") ?? 10; }}- The secrets load while the application initializes. If Anchor cannot be reached or the token
is refused, startup fails with an
AnchorError: the service never starts without its configuration. AnchorServicereads synchronously:get(key)(orundefined),getOrThrow(key)(throwsAnchor secret KEY is not set),has(key),keys()andtoObject()(every value, frozen all the way down: nestedjsonobjects andlistarrays cannot be changed).refresh()fetches now.- Values refresh in the background: a read of values older than the cache
ttlMs(default one minute) returns them at once and starts one refresh. Read a value where you use it to see changes; a value copied into a connection pool at startup stays as it was. - Values are decoded by their type: a
numbersecret is a number, abooleana boolean,jsonandlistare parsed;stringandpemstay strings. - The module is global, so feature modules can inject
AnchorServicewithout importing it. PassisGlobal: falseto change that. Every client option below (cache,retry,onEvent, …) can be passed toforRoot.
To take the options from other providers, for example the environment name from ConfigService:
AnchorModule.forRootAsync({ imports: [ConfigModule], inject: [ConfigService], useFactory: (config: ConfigService) => ({ project: "zepo", environment: config.getOrThrow("APP_ENV"), path: "/shared", }),});Apps that read process.env
Section titled “Apps that read process.env”If the app already reads its configuration from process.env, for example through
@nestjs/config, copy the secrets into the environment before Nest starts, and import the app
module only after that:
import { NestFactory } from "@nestjs/core";import { loadAnchorEnv } from "@anchor-secrets/nestjs";
async function bootstrap() { await loadAnchorEnv({ project: "zepo", environment: "prod", path: "/shared" }); // Imported here: ConfigModule.forRoot reads and validates process.env when app.module loads. const { AppModule } = await import("./app.module"); const app = await NestFactory.create(AppModule); await app.listen(3000);}void bootstrap();loadAnchorEnv writes each value as the string Anchor stores, so ConfigService.get returns
strings (let your validation schema convert them). A variable that is already set wins, so a
local override still works; pass override: true to let Anchor win. It writes nothing unless the
whole folder loads, and never logs a value. process.env is written once: these values do not
refresh.
Since 0.5.3 it skips secrets with reserved names, the ones that change how Node or its child
processes load code or where they connect (NODE_OPTIONS, PATH, LD_PRELOAD, *_PROXY,
ANCHOR_*, …; isReservedEnvKey from @anchor-secrets/sdk tells you which). It reports the
names (never values) once as a process warning,
Anchor skipped reserved names: <names> (set allowReservedKeys to load them), and returns them as
skipped. Pass allowReservedKeys: true to load them anyway.
Any Node service
Section titled “Any Node service”npm install @anchor-secrets/sdkimport { createAnchorClient } from "@anchor-secrets/sdk";
const anchor = createAnchorClient(); // ANCHOR_API_URL and ANCHOR_TOKENconst folder = await anchor.folder({ project: "zepo", environment: "prod", path: "/shared" });
folder.get<string>("DATABASE_URL"); // "postgres://..."folder.get<number>("DB_POOL_SIZE"); // 20client.folder(query)loads the folder once and returns anAnchorFolderwith the same synchronous methods asAnchorService, refreshing in the background.loadSecrets(query)returns{ KEY: value }with values decoded;listSecrets(query)returns each secret with itskey,path,type,sensitive,version,value(a string) andimportedFrom. Both are served from the cache while it is fresh.queryis{ project, environment, path?, expand?, includeImports? }.${...}references are expanded and the folder’s imports are included, as withanchor run, unless you passfalse.listSecretsandloadSecretsalso take{ signal, fresh }: anAbortSignalcancels the call (codeaborted), andfresh: trueasks Anchor even when the cached folder is fresh.
Options
Section titled “Options”createAnchorClient({ apiUrl, // default ANCHOR_API_URL token, // default ANCHOR_TOKEN timeoutMs: 10_000, // per attempt retry: { attempts: 3, baseDelayMs: 250, maxDelayMs: 5_000 }, // or false cache: { ttlMs: 60_000, maxStaleMs: Infinity }, // or false onEvent: (event) => {}, fetch, // replaces the global fetch, for proxies and tests allowInsecureHttp: false, // true allows http:// to hosts other than localhost});Options win over the environment variables.
The API URL must use https://; http:// works only for localhost, 127.0.0.1 and [::1]
(0.5.3). Anything else throws code config before the token is sent. Set allowInsecureHttp: true
only on a network you trust: the token and every value then travel in clear text. The client never
follows a redirect; an API URL that answers with one throws code bad_response
(... answered with a redirect (HTTP 301); use the final address as apiUrl).
Caching
Section titled “Caching”Each client keeps the folders it fetched in memory, keyed by server, token, project, environment,
folder and the expand / includeImports flags. A folder younger than ttlMs is served without
a request, and reads that arrive while a fetch is under way share it. cache: false asks Anchor
on every call.
Anchor tags every folder it sends with an ETag. When a cached folder is older than ttlMs (or
you pass fresh: true), the client sends that tag back as If-None-Match. If nothing in the
folder changed, Anchor answers 304 Not Modified with no body: the client keeps the values it
has, renews their age, and decodes nothing again. With cache: false the client never sends
If-None-Match, so every call returns the full folder (and is audited). Folders cached by SDK
0.4.0 carry no tag; their first refresh is a plain request.
loadSecrets returns fresh objects you may change on every call; an AnchorFolder (and
AnchorService) shares one frozen copy between all readers.
Nothing is written to disk. To keep folders elsewhere, for example in Redis, pass a CacheStore:
import type { CacheStore } from "@anchor-secrets/sdk";
const store: CacheStore = { get: async (key) => decrypt(await redis.get(key)), set: async (key, entry) => void (await redis.set(key, encrypt(entry))),};createAnchorClient({ cache: { store } });A store receives plaintext secret values: encrypt them, and never share one store between
services that should not read each other’s secrets. A store that throws never fails a read: the
client asks Anchor instead, or keeps the fetched values without storing them, and reports
store_failed. Cache keys contain a SHA-256 fingerprint of
the token, never the token itself.
When Anchor is down
Section titled “When Anchor is down”- Network errors, timeouts and HTTP 429, 502, 503 and 504 are retried, by default up to 3
attempts in total, waiting a random time up to 250 ms, then up to 500 ms (doubling, capped at
maxDelayMs). ARetry-Afterheader is honored, up tomaxDelayMs. Other errors fail at once. - When a refresh fails and the client has the folder from before, it serves those values and
reports
refresh_failed. It then waits onettlMsbefore asking Anchor again. This holds for a revoked token (401) too: the service keeps what it had, and new reads stop. maxStaleMslimits how long pastttlMsold values may be served; by default there is no limit. Past it,listSecretsandloadSecretsthrow the refresh error, and anAnchorFolderorAnchorServiceread throws anAnchorErrorwith codestaleuntil Anchor answers again. Set it only if serving old values is worse for you than failing.- The first load has nothing to fall back on: it fails, and a NestJS app does not start.
- Without
maxStaleMs, anAnchorFolderorAnchorServiceread never fails because of the network; a background refresh that fails only reportsrefresh_failed.
Events
Section titled “Events”onEvent receives what the client does about failures, for your logs or metrics. Events never
contain a token or a value, and an exception thrown by the hook is ignored.
createAnchorClient({ onEvent: (event) => { if (event.type === "retry") logger.warn(`Anchor retry ${event.attempt}: ${event.error.code}`); if (event.type === "refresh_failed") { logger.error(`Anchor unreachable, serving values ${event.staleForMs} ms past their ttl`); } if (event.type === "store_failed") logger.error(`Cache store ${event.operation} failed`); },});Errors
Section titled “Errors”Every failure is an AnchorError with a status (0 when there was no response), a code and
retryable:
code |
Meaning |
|---|---|
config |
ANCHOR_API_URL or ANCHOR_TOKEN is missing, or the URL is not https://; nothing was sent |
bad_response |
Anchor answered with a redirect or with something that is not JSON |
network, timeout |
Anchor could not be reached, or did not answer within timeoutMs |
aborted |
The caller’s AbortSignal cancelled the call |
stale |
A folder’s values are older than ttlMs + maxStaleMs and refreshing them failed |
unauthenticated |
The token is wrong, expired or revoked |
forbidden |
The token’s scopes do not cover this environment or folder |
not_found |
The project, environment or folder does not exist |
Error messages never contain the token or a value.