npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

config-pulse

v1.2.0

Published

Push-based runtime config client backed by a single MongoDB document. Pushes runtime/business config into running services without restarts.

Readme

config-pulse

Framework-agnostic, push-based runtime configuration client backed by a single MongoDB document.

A service declares its config once, splitting it into static values (read from env at boot, never changed by a push) and runtime values (changed at any time by a push, without a restart). A control plane (in Beanz: configurations-management) pushes runtime values to PUT /internal/runtime-config; the service persists them, applies them in-process and reports its state back into the same Mongo document.

Migrating a Beanz service? That lives in MIGRATION_GUIDE.md (not shipped to npm). This file only documents the library.

Contents

  1. Concepts
  2. Install and quick start
  3. Declaring config
  4. Wiring a service
  5. HTTP routes
  6. Push, validate and notify
  7. Pod status
  8. What is stored in Mongo
  9. Secrets encoder
  10. Log redaction
  11. Contract tests
  12. Testing
  13. Development (this package's own build/test scripts)
  14. Version history
  15. Known limitations

Concepts

| Term | Meaning | |---|---| | static entry | Read from env at boot (defineConfig). A runtime push can never change it; a pushed static key is reported as unrecognized and ignored. Changing it means changing the ConfigMap/Secret and restarting the pod. | | runtime entry | Starts from env or defaultValue, then follows whatever the control plane pushes. Takes effect without a restart. | | current | The last accepted push, stored verbatim (even keys this service version does not recognise yet). | | resolved | current resolved against the declared entries: defaults filled in, unknown/static keys dropped, missing-required reported. This is what the service applies. | | pod state | One record per pod (ready, failed, ...). Written by the pod itself; there is no heartbeat. |

Effective value per key:

  • static: env value → defaultValue → boot failure if required.
  • runtime: pushed value → defaultValue (the value resolved at boot) → missing (a failure if required).

Everything lives in one collection and one document: __config, _id: "runtime".

Install and quick start

npm i config-pulse   # peer dependency: mongodb >= 4.1.2, node >= 16
import { configPulse, createConfigPulse } from 'config-pulse';

// 1. Declare every key once. Runs at import time: a missing required env exits here.
export const serviceConfig = configPulse.defineConfig({
  static: {
    serviceName: configPulse.staticString({ env: 'SERVICE_NAME', required: true }),
    configReceiverToken: configPulse.staticString({ env: 'CONFIG_RECEIVER_TOKEN', required: true, sensitive: true }),
  },
  runtime: {
    timeoutMs: configPulse.runtimeNumber({ env: 'TIMEOUT_MS', defaultValue: 1000, description: 'Request timeout' }),
    logLevel: configPulse.runtimeString({ defaultValue: 'info' }),
  },
}, { exitCode: 1 });

export const config = serviceConfig.config; // live view: static + runtime

// 2. Start the runtime once Mongo is connected.
const runtime = await createConfigPulse({
  mongo: db,                                            // a mongodb Db (or the __config collection)
  serviceName: config.serviceName,
  podId: process.env.HOSTNAME!,                         // unique per pod
  receiverToken: config.configReceiverToken,            // REQUIRED (or `authorize`): createConfigPulse throws without one
  entries: serviceConfig.getEntries(),
  onChange: ({ config: next }) => serviceConfig.applyRuntimeConfig(next),
});

// 3. Mount the receiver AFTER your body parser, and gate /healthcheck on readiness.
app.use(koaBody());
app.use(runtime.koaMiddleware());
app.use(healthCheckHandler(runtime.health));

process.on('SIGTERM', () => runtime.stop());

createConfigPulse registers the entries, loads any stored current, and leaves the pod ready (stored config applied), receiver_only (waiting for its first push) or failed (required entries missing). It does not start an HTTP server.

Declaring config

Entry builders

configPulse.staticString | staticNumber | staticBoolean | staticJson and runtimeString | runtimeNumber | runtimeBoolean | runtimeJson. Each takes:

| Option | Applies to | Meaning | |---|---|---| | env | both | Env var name, or an array tried in order (first non-empty wins). | | fromEnv(env) | both | Compute the value from the env source instead of env. | | required | both | Fail if no value resolves (see order below). | | defaultValue | both | Fallback value. | | value | static only | Hard-coded value. Runtime entries cannot declare value (throws). | | sensitive | both | Marks the value as secret for consumers that redact (the control plane). Does not redact anything inside this library - see What is stored in Mongo. | | protected | both | Promotion attribute used by the control plane. Absent means true (protected). protected: false opts a key into being copied across environments. | | description | both | Free text surfaced in the console. | | type | both | Override the builder's type: string, number, boolean, json, connectionString. |

Declaration-time errors (thrown, or exit if exitCode is set): sensitive: true together with protected: false is illegal, and a value/defaultValue whose runtime type does not match the entry type is rejected.

Resolution rules worth knowing

  • Order is env → defaultValue → required throws. defaultValue is checked before required, so required: true with a defaultValue can never fire and the entry is effectively optional. Pick one: a required secret has no default; a defaulted value is not required.
  • An empty string counts as absent. FOO='' resolves like an unset FOO. (A legacy typeof process.env.FOO !== 'undefined' check treats '' as present: see the migration guide.)
  • With env: ['A', 'B'] either name satisfies the entry, but when neither is set the error names only the first (Missing required env A).
  • Parsing: number must be finite; boolean accepts true/1/yes/y/on and false/0/no/n/off; json is JSON.parse; connectionString must be a valid URL.

defineConfig(definition, options)

Reads the env once, when it is called, and returns:

| Member | Description | |---|---| | staticConfig | Resolved static values (boot-time snapshot). | | runtimeConfig | Current runtime values (mutated by applyRuntimeConfig). | | config | A Proxy over both. Use this in application code. | | applyRuntimeConfig(values) | Copies every declared runtime key present in values into runtimeConfig. Static and unknown keys are ignored. A runtime key absent from values keeps its previous value, so pass the resolved config from onChange (which already contains defaults), not a raw payload. | | getEntries() | The declarations to hand to createConfigPulse({ entries }). Static entries carry their resolved value; runtime entries carry the current value as defaultValue, so call it at boot, before any push is applied. |

Options: source (an env object or a function returning one; default process.env; a function is invoked once, at call time), exitCode (if set, a failure prints and exits instead of throwing), writeError (default console.error), exit (default process.exit).

The config proxy

| Operation | Behaviour | |---|---| | read a declared key | runtime value if the key is runtime, otherwise the static value. | | read an undeclared key | undefined. | | write a runtime key | takes effect immediately. | | write a static key | silently ignored (the assignment "succeeds") unless NODE_ENV === 'test', where it is applied. | | delete a runtime key | removes it. | | delete a static key | silently ignored outside NODE_ENV === 'test': the key stays in Object.keys(config). | | Object.keys, spread { ...config }, in | work, and reflect current values. |

A key declared in both static and runtime is read from runtime and the static value is shadowed: declare each key once.

EnvConfigLoader

For bootstrap values that are not part of the entries schema. load(schema, source?) throws MissingRequiredEnvError / InvalidEnvError; loadOrExit(schema, { source, exitCode, writeError, exit }) prints and exits. Schema fields: required, type, default, sensitive.

const bootstrap = EnvConfigLoader.loadOrExit({
  SERVICE_NAME: { required: true },
  MONGO_URI: { required: true, type: 'connectionString', sensitive: true },
  PORT: { required: true, type: 'number' },
});

Wiring a service

createConfigPulse(options)

| Option | Description | |---|---| | mongo | A Db (the __config collection is used) or a collection-like object with findOne / updateOne. | | serviceName | Must equal the serviceName the control plane pushes; a mismatch is rejected. | | podId | Unique per pod (HOSTNAME). Used as the key of this pod's record. | | entries | Output of getEntries(). | | receiverToken | Bearer token the default authorizer compares against. | | authorize(ctx) | Custom authorizer; overrides receiverToken. One of the two is required. | | allowUnauthenticated | true lets you omit both (tests and local experiments only). | | validators | { key: (value) => message \| undefined }: value checks, see Value validators. | | onChange(event) | Called when version or checksum changes. event.config is the resolved config. | | onKeyChange | { key: handler }, called only when that key's value changed. | | basePath | Route prefix, default /internal/runtime-config. | | frozen | { reason }. Refuse to accept or apply any config, see Frozen receiver. | | secretsEncoder | { keys, currentKeyId, keysFile, reloadIntervalMs, required, environment }: the secrets encoder. Optional: the key ring is also read from the SECRETS_ENCODER_* environment variables, with no per-service wiring. | | logger | { warn, info? } for key-ring warnings (default console.warn). Never receives a key or a value. | | heartbeatTtlMs, now | now is a clock override for tests. heartbeatTtlMs is accepted but has no effect. |

Returns { store, podStateManager, manager, receiver, statusReporter, handlers, health, getConfig, getCurrent, isReady, koaMiddleware, stop, frozen, keyRing, encryption }.

Authorization

createConfigPulse throws unless you pass receiverToken or authorize. The routes can overwrite the service's config, so a receiver nobody has to authenticate to is never created by accident. allowUnauthenticated: true is an explicit opt-in for tests and local experiments; it has no effect when a token or an authorize is given. (The standalone createKoaRuntimeConfigMiddleware leaves authorize optional: with none, it authenticates nothing.)

The default authorizer is ctx.get('authorization') === 'Bearer ' + receiverToken (plain string comparison, not constant-time). authorize runs only for paths under basePath; other requests pass through untouched.

Value validators

Without validators the library checks presence, not values: a pushed { "limit": -5 } is stored and applied. createConfigPulse({ validators }) adds a check per key:

validators: {
  limit: (value) => (typeof value === 'number' && value > 0 ? undefined : 'limit must be a positive number'),
  mode: (value) => (['fast', 'safe'].includes(value as string) ? undefined : "mode must be 'fast' or 'safe'"),
},
  • A validator returns a message to reject the value, or undefined (or an empty string) to accept it. It may be async; a throw rejects with the error's message.
  • Only keys that have a validator and are present in the push (and not undefined) are checked. A key without a validator is never checked.
  • receive() runs them before persisting: a failing push answers 400 with ok: false, accepted: false, persisted: false and errors.details entries { field, type: 'validator_failed', reason, received? }; nothing is stored or applied, so a bad push can never replace a good current. received is omitted when the entry is sensitive or unknown.
  • POST /validate runs the same validators (ok: true, valid: false plus the details), so a control plane's preflight always agrees with the real push.
  • Not run for an equal-or-older version (the idempotent no-op), for notify, or while the receiver is frozen.
  • Validators guard the push path only. A config stored before validators existed is applied at boot as is; a service that must not apply an invalid stored value validates in its own apply function as well.

Frozen receiver

createConfigPulse({ frozen: { reason } }) makes the receiver refuse all config while it stays reachable. It is a neutral switch: the library does not know why a service is frozen, the service supplies the reason text (for example "runtime config is managed by another source").

While frozen:

  • the entries are registered and GET /entries, GET /pods and POST /pods/prune keep working; GET /readiness answers 503;
  • no stored current is loaded and no pushed config is applied or persisted; the pod stays receiver_only;
  • PUT /, POST /notify and POST /validate answer 409 with an ack carrying frozen: true and error: reason (ok: false, nothing persisted or applied);
  • the low-level ConfigPushReceiver honours the same frozen option, so calling receive() directly cannot bypass it.

A caller (a control plane) can therefore tell "this service is not accepting config" (409 + frozen: true) from a failed push (400) or a stale one.

Koa

runtime.koaMiddleware({ authorize?, basePath? }) (or the standalone createKoaRuntimeConfigMiddleware({ handlers, authorize, basePath })) needs no Koa dependency; it only uses ctx.method, ctx.path, ctx.request.body, ctx.get, ctx.status and ctx.body.

Register it after the body parser. It reads ctx.request.body unconditionally and hands it straight to the receiver. If nothing parsed the body, a PUT arrives as undefined and receive() throws Cannot read properties of undefined (reading 'serviceName'). Read-only routes (GET .../pods, /readiness) keep working, which is why this is easy to miss.

Other frameworks

runtime.handlers (or createRuntimeConfigHttpHandlers) exposes push, notify, validate, prune, status, readiness and entries, each returning { status, body }. createRuntimeConfigHttpDispatcher({ handlers, basePath }) maps { method, path, body } to the right handler and returns { handled, status, body }.

Health

runtime.health is { live, ready } where ready is true only while the config is loaded and applied. It has the same shape as the serverStatus argument of Beanz's healthCheckHandler. To combine it with your own server status use createRuntimeConfigHealthStatus(serverStatus, runtime).

Low-level composition

ConfigDocumentStore, PodStateManager, RuntimeConfigManager, ConfigPushReceiver and ConfigStatusReporter are exported for custom composition (see createConfigPulse in index.ts for the exact wiring). Subscribe with manager.subscribe(handler) or manager.subscribe('key', handler).

HTTP routes

Default base path /internal/runtime-config. All routes sit behind the authorizer above.

| Route | Handler | Success | Failure | |---|---|---|---| | PUT / | push | 202 | 400 (invalid or rejected, see ack); 409 frozen | | POST /notify | notify | 202 | 409 (current config does not match, or frozen); 400 malformed body | | POST /validate | validate | 200 | 400; 409 frozen; 501 if the receiver has no validate | | GET /pods | status | 200 with { current, resolved, counts, pods } | | | POST /pods/prune | prune | 202 with { ok, pruned } (body { podIds }) | 501 if no pruner is wired | | GET /readiness | readiness | 200 { ready: true } | 503 { ready: false } | | GET /entries | entries | 200 { serviceName, entries } | 501 for a hand-built handlers without entriesProvider |

GET /entries is the schema pull: the control plane reads each entry's scope, type, required, sensitive, protected and description without the client registering anything at boot. createConfigPulse always wires it.

Push, validate and notify

A push is { serviceName, version, checksum, config } (plus optional packageId, pushedAt, appliedAt). Build the checksum with the exported helper so it matches what the receiver recomputes:

import { calculateConfigChecksum } from 'config-pulse';

const config = { logging: { level: 'debug' }, featureX: true };
const payload = { serviceName: 'orders', version: 7, checksum: calculateConfigChecksum(config), config };

receive() outcome, in order:

  1. Frozen: refused with frozen: true (409). A body that is not a JSON object, or whose config is not a JSON object (no body parser ran, empty PUT, wrong content type): ok: false with error: 'payload must be a JSON object' / 'config must be a JSON object' (400), never an exception.
  2. serviceName mismatch, non-integer or negative version, or checksum mismatch → ok: false, nothing written.
  3. version ≤ stored current.version: equal version with a different checksum → ok: false (version checksum mismatch); otherwise an idempotent no-op, ok: true, applied: false. Only a strictly higher version is persisted.
  4. If validators are configured, the pushed values are checked before anything is written (see Value validators): any failure → ok: false, errors.details entries of type validator_failed, nothing persisted or applied (400).
  5. Otherwise current is written before it is applied. If applying throws, the ack is ok: false, durable: true, persisted: true, applied: false: the config is stored but this pod did not apply it.
  6. applied is false when required entries are missing (errors.missing), even though ok is true.

Shape validation (presence and unrecognized keys) never blocks a push; only validators do:

  • unknown keys are stored in current.config, listed in errors.unrecognized, and excluded from resolved.config;
  • pushed keys declared static are stored, listed in errors.unrecognized, and do not override the static value;
  • missing required entries are listed in errors.missing and mark the pod failed / not ready.

errors.details repeats this per field (field, type, reason, optional expected / received). received is omitted whenever the entry's sensitive flag cannot be confirmed false, including for keys with no matching entry, so a validation error never echoes a secret. details is typed optional only so older fixtures compile; the library always populates it.

{
  "ok": true, "durable": true, "accepted": true, "persisted": true, "applied": false,
  "version": 7, "currentVersion": 7,
  "errors": {
    "missing": ["apiToken"],
    "unrecognized": ["futureFlag", "serviceUrl"],
    "details": [
      { "field": "apiToken", "type": "missing", "reason": "required value was not provided", "expected": "string" },
      { "field": "futureFlag", "type": "unrecognized", "reason": "key is not declared in the service configuration schema" },
      { "field": "serviceUrl", "type": "unrecognized", "reason": "key is declared as a static entry and cannot be set by a runtime push", "received": "http://orders" }
    ]
  }
}

Validate (POST /validate) runs the same checks and the same equal-or-older-version outcomes as receive() but never writes or applies. Response: { ok, valid, version?, errors?, error? }; validator failures give ok: true, valid: false with the same errors.details a push would be rejected with; valid is false when required entries would be missing.

Notify (POST /notify) takes { serviceName, packageId?, version, checksum }, sent after one pod has seeded Mongo with the full config. The notified pod reads current from Mongo, checks version and checksum match, applies it and updates its own state. It never trusts the notification as the config source. A non-matching current is ok: false (409).

Exported helpers: calculateConfigChecksum, resolveRuntimeConfig(entries, config) (the same resolver both sides use) and findProtectedUnset(entries, targetValues) (promotion preflight: protected fields with no value in the target).

Pod status

GET /pods derives each pod's status from its record:

| Status | Meaning | |---|---| | receiver_only | Started without matching config; accepts pushes, not ready. | | ready | Latest config loaded and applied. | | diverged | Marked ready but on a different version / checksum than current (computed when read). | | failed | Required entries missing, or applying config threw. | | down | Marked on runtime.stop(). |

Every pod record also carries encryption: { version: 'v1', keyIds: [...] } (1.2.0-beta, additive): see Capability report.

stale and expired exist in the type but this library never produces them. There is no heartbeat and no time-based expiry; a pod's record is only rewritten when it applies, fails, enters receiver-only mode or stops. Records of pods that no longer exist are removed by the control plane through POST /pods/prune.

onChange / onKeyChange are called synchronously and not awaited. A synchronous throw marks the pod failed. A rejected promise from an async handler is not caught: the pod is already marked ready and the rejection becomes an unhandled rejection. Catch errors inside async handlers.

What is stored in Mongo

{
  "_id": "runtime",
  "static": { "entries": { "timeoutMs": { "scope": "runtime", "type": "number", "defaultValue": 1000 } } },
  "current": { "serviceName": "orders", "version": 7, "checksum": "...", "config": { "timeoutMs": 2500 } },
  "resolved": {
    "config": { "timeoutMs": 2500 },
    "keys": { "timeoutMs": { "status": "used", "source": "runtime", "scope": "runtime", "type": "number" } },
    "errors": { "missing": [], "unrecognized": [], "details": [] }
  },
  "pods": { "orders-abc12": { "status": "ready", "version": 7, "checksum": "...", "lastSeenAt": "..." } }
}

Static values are stored in plaintext, except entries declared sensitive: true when a secrets-encoder key is configured (they are stored as envelopes, see Secrets encoder). getEntries() puts each resolved static value into its entry, createConfigPulse writes those entries to static.entries, and resolved.config repeats them; GET /pods and GET /entries return them. sensitive: true marks the entry for downstream redaction but does not stop this library persisting or returning the value. Without a key, anyone with read access to the service database, or holding the receiver token, can read every declared static value, including secrets. Declare a secret as a library entry only if you accept that, or keep it out of the entries schema (read it with EnvConfigLoader or process.env).

Secrets encoder

Sensitive values are kept encrypted at rest in every service database and decrypted only in memory (authenticated encryption, AES-256-GCM; one key ring per environment; fail closed). The library does this by default for every service: no per-service wiring and no classification needed on the service side, because a ciphertext is self-describing. Without keys and without envelopes nothing changes: plaintext configs keep working exactly as before. ZooKeeper is not involved.

Envelope

enc:v1:<keyId>:<nonce>:<ciphertext+tag>        (nonce and ciphertext+tag are base64url)
  • AES-256-GCM through node:crypto (no dependency), a fresh random 12-byte nonce per encryption, a 128-bit tag appended to the ciphertext.
  • The value is JSON.stringify-ed before encryption, so any JSON type round-trips (string, number, boolean, null, array, object).
  • keyId selects the key out of the ring, which is what makes rotation possible.
  • AAD (what binds a ciphertext to its place): `${serviceName}|${path}` (UTF-8), built by the single exported pure function buildAad({ serviceName, path }). serviceName is the service's name, path is the dotted config path of the value (dbPassword, db.password; array items by index, hosts.0). serviceName must not contain |. A ciphertext moved to another field or service fails authentication. The environment is not part of the AAD: every environment has its own key, so a ciphertext of one environment cannot be decrypted with another's key. Anything that produces or reads envelopes for config-pulse (the hub included) must use this function or an identical construction.
  • A string starting with enc:v1: is always treated as an envelope. A malformed one is a hard failure, not a plaintext value.

Public API (what the hub reuses)

import {
  isEnvelope, parseEnvelope, encryptValue, decryptValue, buildAad, loadKeyRing,
  decryptConfigEnvelopes, SecretsEncoderError,
} from 'config-pulse';

const ring = loadKeyRing({ keys: { 'beanz-qa-202610': key }, currentKeyId: 'beanz-qa-202610' });
const ctx = { serviceName: 'orders', path: 'db.password' };

const envelope = encryptValue({ user: 'u', password: 'p' }, ctx, ring);   // current key
const value = decryptValue(envelope, ctx, ring);                           // any ring key

| Export | Meaning | |---|---| | isEnvelope(value) | true for a string that starts with enc:v1:. | | parseEnvelope(text) | Strict parse to { version, keyId, nonce, ciphertextAndTag }; throws SECRET_DECRYPT_FAILED (reason: 'malformed'). | | encryptValue(plain, ctx, ring) | Encrypts any JSON value with the ring's current key. Throws SECRETS_ENCODER_KEY_MISSING without one. | | decryptValue(envelope, ctx, ring) | Decrypts with the key named by the envelope. Throws SECRET_DECRYPT_FAILED. | | buildAad(ctx) | The AAD bytes (above). | | loadKeyRing(options) | Reads the key ring (sources below); returns a KeyRing. | | decryptConfigEnvelopes(config, { serviceName }, ring) | Copy of a config object with every envelope decrypted (deep, dotted paths). | | environmentOfKeyId(keyId) | Hub helper: the environment name of a conventional keyId (beanz-qa-202610 gives beanz-qa), or undefined. | | assertKeyIdBelongsToEnvironment(keyId, environmentName) | Hub helper (pure): throws SECRETS_ENCODER_KEY_ENVIRONMENT_MISMATCH unless the keyId is <environmentName>-<suffix> (suffix without -). | | KeyRing | keyIds(), currentKeyId, getKey(id), getCurrent(), reload(), onChange(cb), stop(); toJSON / inspect show key ids only. | | SecretsEncoderError | code, serviceName, path, keyId, reason. The message names only code, service, path and keyId, never a value or a key. |

Service setup

A service enables the key ring with one variable and a mounted secret. It does not need to know its environment.

| Variable | Value | Meaning | |---|---|---| | SECRETS_ENCODER_KEYS_FILE | /etc/secrets-encoder/keys | The variable a service sets. Path of the mounted key ring file (lines keyId:base64url-key, one current: keyId). | | SECRETS_ENCODER_REQUIRED | true (optional) | The pod refuses to start without a key (SECRETS_ENCODER_KEY_MISSING). Set it once the key exists. | | SECRETS_ENCODER_KEYS_RELOAD_MS | 60000 (optional) | How often the file is re-read, so a rotation reaches the pod without a restart. 0 turns it off. |

The mount may be optional: true: a pod in an environment that has no ring yet (no keys file) starts without a key, logs one warning (key file ... not found: secrets encoding is off until it appears) and picks the key up within the reload interval (default 60 s) once the secret exists, with no restart. Set SECRETS_ENCODER_REQUIRED=true only when the key must exist at boot.

Pod template (secret secrets-encoder, item keys mounted as the file keys; no subPath, otherwise rotation does not propagate; optional: true is fine until the key exists):

volumes:
  - name: secrets-encoder
    secret:
      secretName: secrets-encoder
      optional: true
      items: [{ key: keys, path: keys }]
containers:
  - name: <container>
    volumeMounts:
      - { name: secrets-encoder, mountPath: /etc/secrets-encoder, readOnly: true }   # no subPath
    env:
      - { name: SECRETS_ENCODER_KEYS_FILE, value: /etc/secrets-encoder/keys }

The key is never created by hand. Setup is done from the configurations-management repo with the script (dry run by default, --apply executes):

npm run secrets:add-key -- add --env <environmentName> --namespace <ns>           # dry run
npm run secrets:add-key -- add --env <environmentName> --namespace <ns> --apply

It creates the same ring in the hub namespace and in the environment namespace(s) (repeat --namespace), and prints what each deployment must mount. Full runbook (rotation, retire, status): docs/secrets-encoder-key-rotation.md in the configurations-management repo (not shipped in this package).

Key id convention: <environmentName>-<suffix>, default suffix YYYYMM, suffix without -. The current dev environments are beanz-dev, beanz-dev1 and beanz-dev2, so a key id looks like beanz-dev1-202610.

Key ring

Sources, in this order (the first source that is set is used; they are not merged):

  1. option secretsEncoder: { keys: { keyId: base64urlKey }, currentKeyId }
  2. a key file: option secretsEncoder.keysFile or env SECRETS_ENCODER_KEYS_FILE (a mounted Kubernetes secret). Lines keyId:base64url-key, one current: keyId line (or env SECRETS_ENCODER_CURRENT), # comments and blank lines allowed.
  3. env SECRETS_ENCODER_KEYS: comma list keyId:key,keyId:key; the current key is SECRETS_ENCODER_CURRENT
  4. env SECRETS_ENCODER_KEY: one key, keyId default

A service needs only SECRETS_ENCODER_KEY, SECRETS_ENCODER_KEYS or SECRETS_ENCODER_KEYS_FILE (plus the optional SECRETS_ENCODER_REQUIRED). It does not need to know its environment: it loads the ring mounted for its own environment and everything works. The hub handles several environments, so it selects the ring by environment and checks the keyId convention: the keyIds of an environment start with <environmentName>- and end in a suffix without - (for example beanz-qa-202610). The library does not enforce the convention when a service loads its ring; it exports environmentOfKeyId and assertKeyIdBelongsToEnvironment for the hub.

Rules: one current key encrypts, every listed key decrypts. A key must be exactly 32 bytes encoded as base64url (openssl rand -base64 32 | tr '+/' '-_' | tr -d '='); a keyId matches [A-Za-z0-9._-]{1,64} and is not current; duplicate keyIds, a bad length, several keys without a current key, or a current key that is not listed are errors (SECRETS_ENCODER_KEY_INVALID at startup). A single listed key is current by default.

| Option / env | Meaning | |---|---| | secretsEncoder.required or env SECRETS_ENCODER_REQUIRED=true | No key configured at startup throws SECRETS_ENCODER_KEY_MISSING. | | secretsEncoder.reloadIntervalMs or env SECRETS_ENCODER_KEYS_RELOAD_MS | How often the key file is re-read. Default 60000; 0 turns the timer off. |

Key file missing at startup.

| Key file at startup | required false (default) | required true | |---|---|---| | does not exist (ENOENT, ENOTDIR) | One warning, starts with no key (hasKey() false, capability keyIds: []), keeps watching the path; the reload timer loads it when it appears. | Throws SECRETS_ENCODER_KEY_INVALID (cannot read the key file ... (ENOENT)). | | unreadable (EACCES, EISDIR, EIO), empty, malformed, bad key length, duplicate ids, several keys without a current key, no key listed | Throws SECRETS_ENCODER_KEY_INVALID (fail closed). | Same. | | valid | Loaded. | Loaded. |

While there is no ring, plaintext is stored and applied as received and any enc:v1: envelope still fails closed (SECRET_DECRYPT_FAILED, reason no_key). A file that appears later and is invalid keeps "no key" and logs one warning; a file that vanishes after a good load keeps the previous ring.

File reload (rotation without a restart). The key file is re-read periodically on an unref'd timer (keyRing.reload() does it on demand). A re-read that fails, is invalid or yields no key keeps the previous ring and logs one warning (keeping the previous key ring); the ring never silently drops to "no key". Keys that come from environment variables only change with a restart. Key material is never logged, never put in an error message and never shown by JSON.stringify / util.inspect of the ring.

Behaviour

  • Decrypt on apply. Any envelope in a pushed or stored config (any depth) is decrypted with the ring in memory before it is validated and applied. getConfig(), getCurrent(), onChange and onKeyChange always see plaintext; validators check the decrypted value, and a value that arrived as ciphertext is never echoed in errors.details[].received.
  • Ciphertext stays ciphertext; sensitive plaintext is encrypted before it is persisted. current and resolved in the service database keep an envelope as an envelope, and the library never writes a decrypted copy. When a current key exists, a PLAINTEXT value for an entry declared sensitive: true, static or runtime (path = the entry key; objects and arrays are encrypted as a whole) is encrypted before current and resolved are written, whatever path it arrived by: the service's own version-0 seed, a plaintext push from the hub, a replay. Validators, getConfig(), onChange and the push ack keep working on the plaintext; version and checksum stay those of the received payload. Values that already are envelopes, null and non-sensitive declared (static or runtime) keys are stored as received (undeclared keys: see the next bullet). A pushed package may carry static keys: the receiver still reports them unrecognized and does not apply them, but a sensitive one is persisted encrypted in current. Without a key nothing changes: plaintext stays plaintext. GET /pods therefore returns ciphertext for those values.
  • Undeclared keys are encrypted too (1.2.0-beta.4). The control plane, not the service, knows what is secret. With a current key, a pushed top-level key the service does NOT declare (no entry of that name) is stored as an envelope in current (path = the key, any JSON value except null), so it never appears as plaintext in the service database nor in GET /pods. The ack still reports it unrecognized (without echoing the value) and nothing of it is applied. The hub additionally sends sensitiveKeys in the push payload, the top-level keys its effective schema classifies as sensitive (names only, optional, not part of the checksum, not persisted, ignored by older libraries); the receiver encrypts those too, declared or not. Without a key nothing changes (plaintext as received). Escape: secretsEncoder: { encryptUndeclared: false } stores undeclared keys as received (the sensitiveKeys hint is still honoured). GET /pods shows ciphertext (enc:v1:...), never plaintext, for these values; the hub decrypts it with the same ring (AAD serviceName|path).
  • Service-declared sensitive entries. An entry declared sensitive: true whose value / defaultValue comes from the service (boot defaults, env values) is encrypted (path = the entry key) before it is written to static.entries, when a current key exists. GET /entries therefore returns ciphertext for those fields. Without a key they stay plaintext, as before.
  • Fail closed. An envelope that cannot be decrypted (unknown keyId, wrong key, tampered part, AAD mismatch, malformed, or no key at all) throws SECRET_DECRYPT_FAILED naming only service, path and keyId. At startup createConfigPulse rejects when the stored config cannot be decrypted (the pod record says failed). A push (and POST /validate) answers 400 with ok: false, persisted: false and code: 'SECRET_DECRYPT_FAILED' when anything it needs cannot be decrypted: an envelope in the pushed config, or an encrypted entry already stored in the service database (for example a key removed from the ring). This is checked BEFORE the push is written, so nothing is persisted and the current config stays unchanged (a restart still loads the previous good config). Once the missing key is in the ring, the same push succeeds. Ciphertext is never served as a value, with or without a key.

| Code | When | |---|---| | SECRET_DECRYPT_FAILED | an envelope cannot be decrypted (reason: malformed, no_key, unknown_key_id, authentication_failed, invalid_plaintext) | | SECRETS_ENCODER_KEY_MISSING | required and no key at startup, or encrypting without a current key | | SECRETS_ENCODER_KEY_INVALID | a configured key source is unreadable or invalid | | SECRETS_ENCODER_KEY_ENVIRONMENT_MISMATCH | (hub helper) a keyId does not follow the <environmentName>-<suffix> convention for the environment | | SECRET_ENCRYPT_FAILED | the value is not JSON-serialisable, or the context is invalid |

Capability report

Each pod record (GET /pods, pods.<podId> in __config) carries

{ "encryption": { "version": "v1", "keyIds": ["qa-202609", "qa-202610"] } }

Key ids only, never keys. keyIds is empty when no key is configured; the field is absent on pods running an older library. It is republished when a key-file reload changes the key ids. The hub sends ciphertext only to pods whose keyIds contain the key it used, and plaintext (over TLS) to the others. createReceiverContract checks the field.

Rotation (summary)

Rotate one environment at a time with the runbook (docs/secrets-encoder-key-rotation.md once T105 ships; KB page 23): 1) add the new key as decrypt-only to the services' and the hub's key files (about 1 minute to propagate, no restart) and verify every pod reports the new keyId; 2) make the new key current in the hub; 3) re-encrypt stored values and re-deliver; 4) verify nothing uses the old keyId; 5) remove the old key from the services' ring first, then the hub's. A wrong or missing key never corrupts data: decryption fails closed.

Log redaction

The receiver token (x-config-token / Authorization: Bearer ...), API keys and cookies must never reach a log line. The package provides the redaction so each service does not hand-roll it. All helpers are dependency-free, framework-agnostic, return copies, and are exported from config-pulse:

| Export | Meaning | |---|---| | redactHeaders(headers, options?) | Copy of a header object with authorization, proxy-authorization, cookie, set-cookie, x-config-token, x-api-key, x-auth-token, x-access-token, x-csrf-token, and any header whose name contains token / secret / api-key / password / cookie / session ... replaced by [REDACTED] (case-insensitive). | | redactUrl(url, options?) | URL or path?query with credential query parameters (apiKey, token, access_token, key, sig, password, ...) and user:password@ replaced by [REDACTED]. | | redactText(text, options?) | Free text: Bearer ... / Basic ... values, URL credentials, credential query parameters, and every non-empty literal in options.secrets (pass the receiver token), however short; a short secret over-redacts innocent text that contains it, so configure long tokens. | | requestLogRedactor(options?) | Returns (request) => { method, url, headers }, all redacted. Accepts a Koa ctx, ctx.request or a Node IncomingMessage. | | redactForLog(value, options?) | Deep copy of any loggable value: credential-named keys redacted, strings through redactText, errors reduced to name and message, cycles cut. | | REDACTED, SENSITIVE_HEADER_NAMES | The placeholder and the built-in header list. options.headers / options.queryParams add names. |

A service's request logger adopts it with one change:

import { requestLogRedactor } from 'config-pulse';
const safe = requestLogRedactor({ secrets: [config.configReceiverToken] });

// before: logger.info({ method: ctx.method, url: ctx.originalUrl, headers: ctx.headers });
logger.info(safe(ctx));

The package's own logging (key-ring warnings, env-load errors) goes through the same redaction and never contains the receiver token.

Contract tests

config-pulse/testing exports createReceiverContract(options), framework-agnostic cases that run a service's real HTTP stack against its receiver. They catch wiring mistakes the library cannot see: a receiver mounted ahead of the body parser, a missing token check, a service middleware that answers for the receiver routes.

import { createReceiverContract } from 'config-pulse/testing';

for (const { name, run } of createReceiverContract({
  callback: webServer.callback(),           // the service's Koa app.callback()
  token: 'test-token',                      // the token the service accepts
  serviceName: 'orders',
  staticKey: { name: 'port', read: () => config.port },
  // frozen: true,                          // for a frozen receiver
})) {
  it(name, run);
}

Cases: every receiver route answers 401 without a token or with a wrong one; other routes (default /healthcheck) are not gated by the receiver token; GET /entries and GET /pods are served; a PUT without a body answers 400; POST /validate is a dry-run (a valid payload answers 200 and changes nothing; no body answers 400); a valid push is applied (202) and the pod becomes ready (a 400 here usually means the receiver sits ahead of the body parser); a pushed static key is ignored and reported unrecognized; every pod record announces encryption: { version: 'v1', keyIds }; a push with an undecryptable envelope answers 400 SECRET_DECRYPT_FAILED and leaves the current config unchanged. With frozen: true: GET /readiness answers 503, and a push or POST /validate answers 409 with frozen: true.

Testing

  • With NODE_ENV === 'test', writes to static keys on the config proxy are applied (outside tests they are ignored), so specs can override static values.
  • defineConfig evaluates at import time. When a service passes a test source shim, every required: true static entry needs a fallback in it, otherwise the process exits at import with Missing required env X before any spec runs. See the migration guide.
  • Use the now option of createConfigPulse / PodStateManager / ConfigStatusReporter for deterministic timestamps.

Development (this package's own build/test scripts)

npm run build / npm test / npm publish (via prepublishOnly) work when run from a full clone of the configurations-management monorepo, with this package at its usual packages/runtime-config-client/ path - they are monorepo-scoped, not standalone:

  • build runs tsc with no local typescript devDependency of its own - it resolves the binary from the monorepo root's node_modules/.bin (npm adds every ancestor directory's node_modules/.bin to PATH when running a script, which is what makes this work without a package-local install). This package's own tsconfig.json also extends "../../src/tsconfig.json" - the root's own compiler settings - specifically so a standalone build here stays byte-identical to the monorepo's own npm run build:runtime-config-client, rather than drifting from it over time.
  • test explicitly cds to the repository root and delegates to the root's own npm run test:runtime-config-client script, because this package's real test suite (five spec files) lives in the root's shared test/runtime-config-client/ directory, not inside this package - a deliberate choice so the package is tested exactly as the rest of the app sees it, not in isolation.

None of this affects a real npm install config-pulse consumer: the published package (see files above) ships only dist/, testing.js/testing.d.ts, README.md and LICENSE - never the TypeScript source, tsconfig.json, or these scripts' own relevance. A consumer never runs build/ test and is unaffected by any of the above. These scripts exist for a contributor working inside the monorepo checkout, not for extracting this directory into an isolated clone of its own.

Version history

| Version | Adds | |---|---| | 0.1.0 - 1.0.1 | Published on npm (the registry's latest is 1.0.1): defineConfig, entry builders, createConfigPulse, Koa middleware. | | 1.1.0-beta | Everything developed since 1.0.1: POST /validate, errors.details with sensitive-aware received, the protected attribute and findProtectedUnset, GET /entries (schema pull), sensitive behaviour (sensitive + protected: false rejected), the frozen receiver, a 400 ack for a missing or malformed body, the config-pulse/testing contract tests, createConfigPulse refusing to start without receiverToken or authorize, and value validators. |

| 1.2.0-beta | Secrets encoder: enc:v1: envelopes (AES-256-GCM), the key ring (option, key file with periodic reload, SECRETS_ENCODER_KEYS, SECRETS_ENCODER_KEY), decrypt-on-apply, ciphertext kept in the service database, encryption of service-declared sensitive entries, fail-closed SECRET_DECRYPT_FAILED / SECRETS_ENCODER_KEY_MISSING, the encryption capability in every pod record, the exported encryptValue / decryptValue / parseEnvelope / isEnvelope / loadKeyRing / buildAad API. Additive: nothing changes without keys and envelopes. | | 1.2.0-beta.2 | With a key, a plaintext value of a runtime entry declared sensitive: true is stored encrypted in current and resolved (seed, plaintext push, replay); validators, getConfig(), onChange and acks still see plaintext; no change without a key. | | 1.2.0-beta.3 | Fix: a configured SECRETS_ENCODER_KEYS_FILE that does not exist yet (ENOENT / ENOTDIR) no longer crashes the pod at boot unless SECRETS_ENCODER_REQUIRED is set. It logs one warning, starts with no key (unchanged behaviour) and the reload timer picks the file up when it appears. Every other read or parse failure still throws SECRETS_ENCODER_KEY_INVALID. | | 1.2.0-beta.4 | With a key, pushed keys the service does not declare are stored encrypted (GET /pods never shows their plaintext); the push payload may carry sensitiveKeys (hub classification, optional, honoured for declared keys too, never persisted); escape secretsEncoder.encryptUndeclared: false. Log redaction helpers: redactHeaders, redactUrl, redactText, requestLogRedactor, redactForLog. Additive; nothing changes without a key. | | 1.2.0 | Stable release. The code is byte-identical to 1.2.0-beta.4 (secrets encoder, sensitive values encrypted at rest, undeclared keys encrypted, missing key file tolerated, sensitiveKeys hint, log redaction helpers); only the version differs. Additive over 1.0.1. Published as latest. |

Update: 1.2.0 is the stable release (the content of 1.2.0-beta.4), published as latest; services that declared ^1.0.1 receive it on their next install, and the migrated services pin it exactly ("config-pulse": "1.2.0"). The paragraph below describes the earlier beta-only plan.

The package.json in this repo carried internal numbers 1.1.0 - 1.5.0 that were never published; the first publish after 1.0.1 is 1.1.0-beta.N (secrets encoder: 1.2.0-beta.N) (publish with npm publish --tag beta), so ^1.0.1 ranges do not pick it up. Every service currently installs 1.0.1, so none of them serves GET /entries or POST /validate yet. Opt in with the exact version ("config-pulse": "1.1.0-beta.N").

Known limitations

These are properties of the current code, listed so they are not rediscovered in production:

  • The default token comparison is not constant-time (pass authorize with a constant-time check if that matters).
  • Static values, including secrets, are persisted to and returned from the service's __config document (encrypted only for sensitive entries when a secrets-encoder key is configured).
  • Plaintext already stored in current / resolved before a key was configured (or before 1.2.0-beta.2) is not rewritten at startup; it is encrypted when the next version is received. Values of entries that are NOT declared sensitive, static or runtime, are always stored as received (readable on purpose, so they can be compared).
  • The secrets encoder protects the database, not the process: a pod holds its environment's key. Keys from environment variables only change with a restart; use the key file for rotation without one.
  • onChange handlers are not awaited, and async rejections are not surfaced as pod failures.
  • heartbeatTtlMs and the stale / expired statuses are unused.
  • A runtime key without a defaultValue that disappears from a push keeps its previous value in applyRuntimeConfig (the resolved config simply omits it).

License

MIT