@anmho/auth-client

TypeScript client-credentials token refresher for long-running Node services.

The package reads OAuth client credentials from Vault using the node-vault SDK, exchanges them for a Bearer access token, keeps that token cached in the background, and exposes getToken().

Install

npm install @anmho/auth-client

Usage

import { ClientCredentialsTokenRefresher, vaultCredentialsProvider } from "@anmho/auth-client";

const refresher = new ClientCredentialsTokenRefresher({
  tokenUrl: "https://auth.anmho.com/api/auth/oauth2/token",
  credentials: vaultCredentialsProvider({
    path: "prod/apps/agent/server/oauth-clients/billing"
  }),
  resource: "api://billing",
  scope: ["invoices:read"]
});

refresher.start();

const token = await refresher.getToken();

Vault

The Vault provider uses the node-vault SDK. It reads KV v2 secrets from the secret mount by default and expects client_id and client_secret fields. Pass endpoint, token, and namespace explicitly, or let it read VAULT_ADDR, VAULT_TOKEN, and VAULT_NAMESPACE.

The default authctl Vault path shape is:

prod/apps/<client_app_id>/<client_identity>/oauth-clients/<resource_server_id>

Behavior

• start() starts an async setInterval refresh loop.
• stop() clears the interval.
• refresh() forces a token request and updates the cache.
• getToken() returns a cached valid token, or performs one foreground refresh if startup refresh has not completed or the token is expired.
• Background refresh failures do not erase the last still-valid token.

Testing

Run the package tests:

bun test packages/auth-client

Run the functional example smoke from the repo root:

bun run examples:smoke

That command starts local Postgres and Vault dev containers, migrates the local auth API database, creates an authctl resource server and OAuth client, writes the one-time client credentials into Vault, and runs the Node and Go example apps against the live local token endpoint.

Release

Version packages/auth-client/package.json independently when the TypeScript runtime client changes. npm publishing is handled by GitHub Actions trusted publishing through .github/workflows/publish-auth-client.yml.

Configure the npm trusted publisher:

@anmho/auth-client -> anmho/auth / publish-auth-client.yml