@open-matrix/nats-auth (0.1.20)
Installation
@open-matrix:registry=npm install @open-matrix/nats-auth@0.1.20"@open-matrix/nats-auth": "0.1.20"About this package
@open-matrix/nats-auth
Shared Node-side helpers for Matrix NATS JWT credential references.
This package owns credential-reference parsing, JWT/seed loading, and temporary user JWT generation from account seeds for Host and runner processes. It also owns the source-tree command that durably replaces an environment service user credential and publishes the exact prior-user revocation to a live full resolver.
Protected service-credential rotation
Run rotation only while the caller has serialized every other writer of the target Account claim:
matrix-nats-hub rotate-account-user-credential \
--state /absolute/path/to/nats-hub-state.json \
--credentials-out /absolute/path/to/current-service-credentials.json \
--credential-protection-marker /absolute/path/to/service-credential-protection.json \
--server nats://127.0.0.1:4222 \
--system-credentials /absolute/path/to/system-resolver-credentials.json \
--credentials-root SPACE-HIVECAST \
--credentials-user hivecast-platform-runtime
--credentials-root defaults to the platform root. Supplying
--credentials-user asserts that the current credential already has that
name; rotation preserves its name, permissions, and lifetime rather than
accepting a new policy on the command line.
The command reads JWTs and seeds from the named files, never from argument values. It verifies the live Account JWT, merges already-live revocations into durable state, creates a replacement user, atomically replaces the state and credential files, publishes a claim that revokes the exact prior user, and then proves all three behavioral joins: the prior connection closes, the prior credential cannot reconnect, and the replacement credential can connect. It does not restart or reconfigure the broker.
Rotation is forward-recoverable, not reversible to the revoked key. Durable state and the current credential file are replaced before the live resolver is updated, so an interruption is recovered by rerunning the same command with whichever credential file is now present. Reinstalling the prior credential is not rollback because its user public key is durably revoked.
Protection marker and output custody
An initial render supplied with --credential-protection-marker creates a
birth-only born-protected marker. A completed rotation replaces it with a
rotated marker containing only the root, Account name and public key, current
and revoked user public keys, and the revocation cutoff. The marker contains no
JWT or seed and grants no authority. It is still durable custody state: the
package writes it atomically with mode 0600, and a later run accepts it only
after proving that the current credential works and the recorded revocation is
present in both local state and the live signed Account claim.
Command output is likewise secret-free: it reports status, public identities, timestamps, and resolved file paths, never JWT or seed values. Do not treat the marker or stdout as a replacement for the credential file.
Inspection boundary
Account inspection exposes public Account and user identifiers, credential
purpose/status, and public import/export topology only. Backend resource
objects, credential references, JWTs, seeds, and credential values do not cross
that boundary. An incomplete user listing makes the whole inspection an error;
it is never silently projected as an empty credential set. The exported
verifyNatsAccountJwt helper cryptographically checks a resolver response and
its expected Account/operator identities before callers use its revocation
fields; it is a verification primitive, not a logging or display surface.
Dependencies
Dependencies
| ID | Version |
|---|---|
| @open-matrix/contracts | 0.1.16 |
| @open-matrix/credential-plane | 0.1.5 |
| @open-matrix/subjects | 0.1.8 |
| nats | ^2.29.3 |
| nkeys.js | ^1.1.0 |
Development Dependencies
| ID | Version |
|---|---|
| @types/node | ^20.0.0 |
| esbuild | ^0.25.0 |
| tsx | ^4.0.0 |
| typescript | ^5.3.0 |