@cotal-ai/core 0.171.1 → 0.171.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/endpoint.js CHANGED
@@ -1,22 +1,16 @@
1
1
  import { EndpointHistory } from "./endpoint-history.js";
2
2
  export { MULTI_FILTER_BATCH, MULTI_FILTER_READ_CONCURRENCY } from "./endpoint-history.js";
3
- import { requestSafeReconnect } from "./request-safe-reconnect.js";
4
3
  import { nativeBindingAfter, nativeConnectionBinding } from "./native-connection.js";
5
4
  import { EventEmitter } from "node:events";
6
5
  import { drainAndClose } from "./connection-cleanup.js";
7
6
  import { randomUUID } from "node:crypto";
8
- import { createConnection, isIP } from "node:net";
9
- import { connect, tokenAuthenticator, nanos, AuthorizationError, PermissionViolationError, UserAuthenticationExpiredError, NoRespondersError, RequestError, TimeoutError, ConnectionError, } from "@nats-io/transport-node";
10
- import { wsconnect } from "@nats-io/nats-core";
7
+ import { nanos, PermissionViolationError, NoRespondersError, RequestError, TimeoutError, } from "@nats-io/transport-node";
11
8
  import { responderFromLease, responderFromProbe, } from "./liveness.js";
12
9
  import { EndpointPresence } from "./endpoint-presence.js";
13
10
  export { PresenceWriteStuckError } from "./endpoint-presence.js";
14
- import { credsClaims, credsFingerprint, credsRenewalDelayMs, idFromCreds } from "./identity.js";
15
- import { nativeCredsAuthenticator } from "./creds-authenticator.js";
16
- import { armRenewal, renewalDeadlineMs, jitteredBackoffMs } from "./renewal.js";
11
+ import { credsClaims, credsRenewalDelayMs, idFromCreds } from "./identity.js";
17
12
  import { requireBrokerFloor } from "./broker-floor.js";
18
13
  import { withDeadline } from "./deadline.js";
19
- import { inspectCredHealth } from "./provision.js";
20
14
  import {} from "./secret-store.js";
21
15
  import { BIND_SPLIT_REISSUES, resolveService } from "./endpoint-invoke.js";
22
16
  import { EpEnvelopeError, respondedButUnbound, replyRefusedBeforeEffect, replyTargetUnmapped } from "./endpoint-envelope.js";
@@ -33,7 +27,6 @@ import { assertValidKind } from "./agent-file.js";
33
27
  import { assertValidName } from "./resolve.js";
34
28
  import { nextHeartbeat } from "./presence-heartbeat.js";
35
29
  import { anycastStoreDefinition, taskDurableConfig, PRESENCE_STORAGE } from "./streams.js";
36
- import { DELIVERY_LIMIT_HEADER, PLANE3_MAX_MSGS_PER_SUBJECT } from "./backup-config.js";
37
30
  import { jetstream, jetstreamManager, AckPolicy, DeliverPolicy, JetStreamApiCodes, } from "@nats-io/jetstream";
38
31
  import {} from "@nats-io/jetstream";
39
32
  import { Kvm } from "@nats-io/kv";
@@ -47,89 +40,22 @@ import { EndpointDurableBackstop } from "./endpoint-durable-backstop.js";
47
40
  import { EndpointSubscriptions, membershipConsumerReleased } from "./endpoint-subscriptions.js";
48
41
  import { EndpointChannelDiscovery } from "./endpoint-channel-discovery.js";
49
42
  import { EndpointLiveness } from "./endpoint-liveness.js";
43
+ import { EndpointCredentials } from "./endpoint-credentials.js";
50
44
  import { EndpointProvisioning } from "./endpoint-provisioning.js";
51
45
  import { EndpointBootMemberships } from "./endpoint-boot-memberships.js";
52
- import { ackWaitOf, authenticatedChannelMessage, durableDelivery, isRecord } from "./endpoint-inbound.js";
46
+ import { ackWaitOf, durableDelivery, isRecord } from "./endpoint-inbound.js";
53
47
  import { openChannelRegistry, effectiveReplay, effectiveReplayWindowMs, readChannelConfig, readChannelDefaults, } from "./channels.js";
54
48
  import { isCasLoss } from "./endpoint-records.js";
55
49
  import { ANYCAST_CANCEL_OP, ANYCAST_NOTICE_KEY, ANYCAST_RECORDS_CREDENTIAL_OUTDATED, ANYCAST_STATUS_OP, ANYCAST_TAKES_OP, AnycastRequestAuthority, isAnycastSeq, } from "./anycast-requests.js";
56
50
  import { assertValidRole, chatStream, chatSubject, controlServiceSubject, CONTROL_DELIVERY, CONTROL_DELIVERY_ADMIN, dmStream, dmDurable, membershipInAllow, isConcreteChannel, isChannelFamily, MENTION_NOTICE_KEY, parseSubject, isPrincipalOwnerToken, assertInboxConnId, presenceBucket, MEMBERSHIP_FEED_KEY, principalKey, parsePrincipalKey, assertLifecycleToken, mintLifecycleUid, lifecycleNameKey, DEV_OWNER, spacePrefix, spaceWildcard, subjectMatches, taskStream, taskDurable, takeServeFilter, takeSubject, parseTakeSubject, TAKE_ROUTE, token, unicastSubject, unicastRecvFilter, } from "./subjects.js";
57
51
  import { isPermissionDenied } from "./permission-denied.js";
58
52
  export { isPermissionDenied };
59
- export const DEFAULT_SERVER = "nats://127.0.0.1:4222";
60
- /** Takes a daemon answers at once; one more is refused as busy, so the holder keeps its copy and
61
- * asks again rather than queueing work the daemon cannot bound. */
62
- const MAX_TAKES_IN_FLIGHT = 64;
63
- /** How often the daemon runs the anycast records maintenance pass. */
64
- const ANYCAST_SWEEP_MS = 10 * 60 * 1000;
65
- /** How long a holder waits for the daemon to answer a take. */
66
- const ANYCAST_TAKE_TIMEOUT_MS = 5_000;
67
- /** The DLV count a stored copy was written under, from its {@link DELIVERY_LIMIT_HEADER} (SPEC §8):
68
- * a whole number of at least 1, null for `none`, and 1000 when the header is absent, since only a
69
- * daemon from before the count was configurable writes a copy without it and its count was 1000.
70
- * Throws on any other value. */
71
- export function deliveryLimitOf(value) {
72
- if (value === undefined || value === "")
73
- return PLANE3_MAX_MSGS_PER_SUBJECT;
74
- if (value === "none")
75
- return null;
76
- if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value)))
77
- throw new Error(`plane-3 delivery: ${DELIVERY_LIMIT_HEADER} ${JSON.stringify(value)} is not a count`);
78
- return Number(value);
79
- }
80
- /** Space joined when none is given on the CLI (the `cotal-<space>` cmux tab, etc.). */
81
- export const DEFAULT_SPACE = "main";
82
- /** The longest delay `setTimeout` honors, 2^31-1 ms. */
83
- const MAX_TIMER_MS = 2_147_483_647;
84
- /** This endpoint's own `dm_` durable does not exist. A DM-only endpoint, and any endpoint on an
85
- * authenticated mesh, binds the durable its provisioner created and never creates one. */
86
- export class DmDurableMissingError extends Error {
87
- stream;
88
- durable;
89
- code = "dm-durable-missing";
90
- constructor(stream, durable) {
91
- super(`dm-durable-missing: durable "${durable}" on stream "${stream}" does not exist; this endpoint binds an existing durable and never creates one`);
92
- this.stream = stream;
93
- this.durable = durable;
94
- this.name = "DmDurableMissingError";
95
- }
96
- }
97
- /** The broker refused a DM-only endpoint's bind of its own `dm_` durable. No other credential or
98
- * read path is tried. */
99
- export class DmBindRefusedError extends Error {
100
- stream;
101
- durable;
102
- code = "dm-bind-refused";
103
- constructor(stream, durable, cause) {
104
- super(`dm-bind-refused: binding durable "${durable}" on stream "${stream}" was refused (${cause instanceof Error ? cause.message : String(cause)})`, { cause });
105
- this.stream = stream;
106
- this.durable = durable;
107
- this.name = "DmBindRefusedError";
108
- }
109
- }
110
- /** The NEWEST prefix-from-the-end of `items` whose serialized `readHistory` reply fits `budget`
111
- * bytes, order preserved. Returns `[]` when not even the newest single message fits — the caller
112
- * must refuse loudly there rather than serve an empty page, which would read as "no history".
113
- *
114
- * The `ControlReply` around the items rides the same NATS message, so it is charged too: items
115
- * that fit on their own can still make a reply the broker refuses.
116
- *
117
- * Measured in ENCODED bytes, not `string.length`: a page of multi-byte text would otherwise be
118
- * undercounted and still overflow the broker. Same discipline as `assertFactFits`. */
119
- export function fitHistoryPage(items, budget) {
120
- const enc = new TextEncoder();
121
- // The reply with no items, at its longer `complete` value.
122
- let used = enc.encode(JSON.stringify({ ok: true, data: { items: [], complete: false } })).length;
123
- let first = items.length; // index of the oldest kept item
124
- for (let i = items.length - 1; i >= 0; i--) {
125
- const size = enc.encode(JSON.stringify(items[i])).length + 1; // + the `,` separator
126
- if (used + size > budget)
127
- break;
128
- used += size;
129
- first = i;
130
- }
131
- return first === items.length ? [] : items.slice(first);
132
- }
53
+ import { DEFAULT_SERVER, isPublishPermissionDenied, dialerFor, isAuthRejection, kvWatchConsumer, decodeBearerPrincipal, bearerRenewalDeadlineMs, authOpts, RepeatedRefusal, describeStatusError, } from "./endpoint-dial.js";
54
+ export { DEFAULT_SERVER, isPublishPermissionDenied, wsServers, defaultProbeTimeoutMs, dialerFor, isAuthRejection, isReachable, probeConnect, } from "./endpoint-dial.js";
55
+ import { MAX_TIMER_MS, ANYCAST_SWEEP_MS, MAX_TAKES_IN_FLIGHT, ANYCAST_TAKE_TIMEOUT_MS, DmDurableMissingError, DmBindRefusedError, } from "./endpoint-options.js";
56
+ export { deliveryLimitOf, DEFAULT_SPACE, DmDurableMissingError, DmBindRefusedError, fitHistoryPage, } from "./endpoint-options.js";
57
+ import { historyMessageFromDelivery, isUsableMessageId, isFromSubjectSender, authenticatedMessage, isReadableMessagePart, kindFromParsed, dmOnlyDelivery, } from "./endpoint-messages.js";
58
+ export { isFromSubjectSender, } from "./endpoint-messages.js";
133
59
  /** The highest `prompts` presence `seq` this process used under each runtime id (SPEC §6). A reader
134
60
  * orders lists by `seq` within one `runtime.id`, and a runtime id lives as long as the process, so
135
61
  * this does too: across a stopped serve, a stopped endpoint and a new endpoint for the lifecycle. */
@@ -710,12 +636,6 @@ export class CotalEndpoint extends EventEmitter {
710
636
  return;
711
637
  this.superviseConnection();
712
638
  }
713
- /** The floor on a bearer renewal's delay. A token whose whole lifetime sits under it is renewed at
714
- * this cadence (`expiry-renewal` mints 5s bearers). */
715
- static BEARER_MIN_RENEWAL_MS = 5_000;
716
- /** A failed bearer renewal retries after about this long, doubling per failure up to the cap. */
717
- static BEARER_RETRY_MS = 5_000;
718
- static BEARER_RETRY_CAP_MS = 60_000;
719
639
  /**
720
640
  * A condition the endpoint is already surviving. Node rethrows `error` when no listener is
721
641
  * attached, so emitting retry notices on `error` killed hosts that the endpoint intended to
@@ -724,461 +644,115 @@ export class CotalEndpoint extends EventEmitter {
724
644
  emitRecoverable(err) {
725
645
  this.emit("warning", err);
726
646
  }
727
- /** Fetch a fresh bearer from the source, pin its principal to ours, arm the next renewal. On a
728
- * fetch/principal failure: THROWS when `initial` (start() must fail loud before first connect);
729
- * otherwise retries on a jittered, capped backoff, and warns once for the whole run of failures —
730
- * the live connection keeps working until its current JWT expiry, so a dead auth service is
731
- * loud without instantly dropping the mesh, and without a line per attempt. */
732
- async refreshBearer(initial = false) {
733
- try {
734
- const bearer = await this.bearerSource();
735
- const claims = decodeBearerPrincipal(bearer);
736
- if (claims.owner !== this.owner || claims.actor !== this.actor)
737
- throw new Error(`bearer source returned principal ${claims.owner}.${claims.actor}, expected ${this.owner}.${this.actor}`);
738
- // Two refusals, answering different questions, and both of them are about protecting what is
739
- // ALREADY held. So both are scoped to there BEING something held, which is the same set as
740
- // `!initial` but names the thing the rules actually depend on: on the first fetch there is no
741
- // cache to lose, `start()` has to come up on whatever the source has, and the pre-dial guard
742
- // in {@link bindConnection} is what speaks for a dead first token.
743
- const expiryMs = bearerExpiryMs(bearer);
744
- const held = this.currentBearer;
745
- if (held !== undefined) {
746
- // ALREADY DEAD, whatever else is true of it. Advancement is deliberately not part of this
747
- // test: a candidate expiring at now-5s does advance a held one that died at now-60s, so an
748
- // advance-only rule adopts it - overwriting the cache with material nothing can dial,
749
- // skipping the recoverable warning because the fetch did not throw, and arming the next
750
- // read off a non-positive delay. The creds path draws its line on expiry alone too, in
751
- // {@link presentableCreds} (#1572).
752
- if (expiryMs <= Date.now())
753
- throw new Error("the bearer source returned a token that has already expired - nothing adopted");
754
- // THE SAME BYTES BACK AGAIN from a source whose token is already past its renewal window:
755
- // the renewal it arms is floored to 5s, and the next read returns that same token - a 5s
756
- // loop against the auth service for the rest of its life, with the retry backoff bypassed
757
- // because the fetch did not FAIL. It succeeded and returned nothing new (#1561).
758
- //
759
- // The test is byte identity, not expiry, and not advancement. `exp` carries one second of
760
- // resolution, so a key rotation re-signing the same claims under a new key - and a healthy
761
- // short-TTL source read twice inside one wall-clock second - both hand back a token whose
762
- // `exp` has not moved. That is genuinely re-issued material, which an advancement test
763
- // refuses and this one adopts. It is the question the creds path asks with
764
- // `credsFingerprint`: did the source re-issue ANYTHING (#1572).
765
- if (bearer === held && Date.now() >= bearerRenewalDeadlineMs(held, this.bearerAdoptedAtMs))
766
- throw new Error("the bearer source re-served the token already held and it cannot carry another cycle (the auth service has not issued a fresh one) - nothing adopted");
767
- }
768
- if (bearer !== held)
769
- this.bearerAdoptedAtMs = Date.now();
770
- this.currentBearer = bearer;
771
- this.bearerRenewalFailures = 0;
772
- // The renewal point is drawn from the middle of the token's lifetime, spaced from this
773
- // process's other renewals in the space: a fixed margin before `exp` kept every endpoint
774
- // issued in one second renewing, and rebinding through the callout, in one second for life.
775
- const { issuedAtMs, expiresAtMs } = bearerLifetimeMs(bearer, this.bearerAdoptedAtMs);
776
- this.armBearerTimer(armRenewal(this.space, issuedAtMs, expiresAtMs, () => void this.renewBearerOnTimer(), CotalEndpoint.BEARER_MIN_RENEWAL_MS));
777
- }
778
- catch (e) {
779
- if (initial)
780
- throw e;
781
- if (this.bearerRenewalFailures === 0)
782
- this.emitRecoverable(new Error(`bearer refresh failed (${e instanceof Error ? e.message : String(e)}) - retrying with backoff; this connection dies at its current token's expiry if the auth service stays down`));
783
- // A wait the source named is kept as named: never retried inside it, nor stretched by the backoff.
784
- const named = retryAfterMs(e);
785
- const delay = named > 0 ? named : jitteredBackoffMs(this.bearerRenewalFailures, CotalEndpoint.BEARER_RETRY_MS, CotalEndpoint.BEARER_RETRY_CAP_MS);
786
- this.bearerRenewalFailures++;
787
- const timer = setTimeout(() => void this.renewBearerOnTimer(), delay);
788
- timer.unref?.();
789
- this.armBearerTimer(() => clearTimeout(timer));
790
- }
791
- }
792
- armBearerTimer(cancel) {
793
- this.cancelBearerRenewal?.();
794
- this.cancelBearerRenewal = cancel;
795
- if (this.stopped)
796
- cancel();
797
- }
798
- /** The timed renewal. A new token moves the live connection onto itself at once, through the
799
- * same controlled reconnect the creds path uses, so the broker never has to expire a connection
800
- * this endpoint could renew. With no live connection, it ends the rebuild loop's wait instead:
801
- * that loop refuses to dial an expired token and leaves the retries to this timer. */
802
- async renewBearerOnTimer() {
803
- const held = this.currentBearer;
804
- await this.refreshBearer();
805
- if (this.stopped || this.currentBearer === held)
806
- return;
807
- if (this.nc && !this.nc.isClosed())
808
- await this.swapConnectionOntoFreshCreds();
809
- else
810
- this.kickBackoff();
647
+ /** The resident swap a reload scheduled, until its connection is back or the gate's bound ends. */
648
+ residentSwap;
649
+ /** Serializes every prove-then-adopt transaction (the 75% timer and the explicit reload) so a timer
650
+ * tick and an explicit reload can never interleave their fetch/preflight/commit — the design's
651
+ * single-flight requirement. Runs `fn` after any in-flight transaction settles, whatever its
652
+ * outcome; the internal chain never rejects. */
653
+ credsTxn = Promise.resolve();
654
+ /** The bearer and credential renewal of this endpoint. Every dependency is read when it is used, so
655
+ * a field assigned after construction is seen. */
656
+ credentials = new EndpointCredentials({
657
+ nc: () => this.nc,
658
+ bearerSource: () => this.bearerSource,
659
+ owner: () => this.owner,
660
+ actor: () => this.actor,
661
+ space: () => this.space,
662
+ currentBearer: () => this.currentBearer,
663
+ setCurrentBearer: (value) => { this.currentBearer = value; },
664
+ bearerAdoptedAtMs: () => this.bearerAdoptedAtMs,
665
+ setBearerAdoptedAtMs: (value) => { this.bearerAdoptedAtMs = value; },
666
+ bearerRenewalFailures: () => this.bearerRenewalFailures,
667
+ setBearerRenewalFailures: (value) => { this.bearerRenewalFailures = value; },
668
+ cancelBearerRenewal: () => this.cancelBearerRenewal,
669
+ setCancelBearerRenewal: (value) => { this.cancelBearerRenewal = value; },
670
+ stopped: () => this.stopped,
671
+ presentedExp: () => this.presentedExp,
672
+ setPresentedExp: (value) => { this.presentedExp = value; },
673
+ currentCreds: () => this.currentCreds,
674
+ setCurrentCreds: (value) => { this.currentCreds = value; },
675
+ credsSource: () => this.credsSource,
676
+ connId: () => this.connId,
677
+ overlapOnConnectionRenewal: () => this.overlapOnConnectionRenewal,
678
+ onConnection: () => this.onConnection,
679
+ servers: () => this.servers,
680
+ card: () => this.card,
681
+ token: () => this.token,
682
+ user: () => this.user,
683
+ pass: () => this.pass,
684
+ userMode: () => this.userMode,
685
+ sentinelCreds: () => this.sentinelCreds,
686
+ tls: () => this.tls,
687
+ ownedConnections: () => this.ownedConnections,
688
+ authExpiryReconnectTimer: () => this.authExpiryReconnectTimer,
689
+ setAuthExpiryReconnectTimer: (value) => { this.authExpiryReconnectTimer = value; },
690
+ credsTxnsRunning: () => this.credsTxnsRunning,
691
+ setCredsTxnsRunning: (value) => { this.credsTxnsRunning = value; },
692
+ credsTxn: () => this.credsTxn,
693
+ setCredsTxn: (value) => { this.credsTxn = value; },
694
+ reconnecting: () => this.reconnecting,
695
+ reestablishing: () => this.reestablishing,
696
+ requestsAwaitingReply: () => this.requestsAwaitingReply,
697
+ residentSwap: () => this.residentSwap,
698
+ setResidentSwap: (value) => { this.residentSwap = value; },
699
+ emitRecoverable: (err) => this.emitRecoverable(err),
700
+ kickBackoff: () => this.kickBackoff(),
701
+ armCredsRefresh: (delayMs) => this.armCredsRefresh(delayMs),
702
+ reconnect: () => this.reconnect(),
703
+ emit: (event, ...args) => this.emit(event, ...args),
704
+ on: (event, listener) => { this.on(event, listener); },
705
+ off: (event, listener) => { this.off(event, listener); },
706
+ });
707
+ /** Forwards to the credentials component's {@link EndpointCredentials.refreshBearer}. */
708
+ refreshBearer(initial = false) {
709
+ return this.credentials.refreshBearer(initial);
811
710
  }
812
- /** The cached bearer, checked: every (re)connect attempt reads it, the reconnects nats.js runs
813
- * on its own included, so none presents an expired token, which the callout could only deny
814
- * after a full round trip. The bearer counterpart of {@link credsForWire}. */
711
+ /** Forwards to the credentials component's {@link EndpointCredentials.bearerForWire}. */
815
712
  bearerForWire() {
816
- const bearer = this.currentBearer;
817
- if (bearer !== undefined && bearerExpiryMs(bearer) > Date.now())
818
- return bearer;
819
- throw new Error(this.bearerSource
820
- ? "this endpoint's user bearer has expired and renewal through the auth exchange is failing - not presenting the expired token to the broker; retrying with backoff"
821
- : "this endpoint's user bearer has expired and it holds no bearer source to renew it - re-authenticate and rebuild the endpoint (construct it with a bearer FUNCTION for standing renewal)");
822
- }
823
- /** How soon a FAILED creds refresh retries. Successful refreshes schedule by lifetime fraction
824
- * (75% of iat→exp), not a fixed margin — standing creds span hours to days, bearers minutes. */
825
- static CREDS_RETRY_MS = 60_000;
826
- /** THE ONE PLACE a credential is cleared for presentation to a broker.
827
- *
828
- * The property is unconditional — this endpoint never presents a credential it has already
829
- * decoded as expired — so it is a property of the SUPPLY, not of any one dial site. It used to
830
- * live inside {@link bindConnection}, which only `start()` and `doRebuild` reach; the
831
- * authenticator nats.js re-evaluates on ITS OWN reconnects read the cache directly and so
832
- * presented whatever was last fetched, expired included. Two such reconnects exist and neither
833
- * passes through bindConnection: the one the broker forces at JWT `exp`, and an ALREADY RUNNING
834
- * dial loop from an earlier drop that crosses `exp` while it retries (the pre-expiry
835
- * reconnect fence flips a policy flag nats-core only reads when it observes a NEW drop, so it
836
- * cannot stop a loop already in flight).
837
- *
838
- * Putting the refusal here instead means a future caller cannot miss it: the only way to reach a
839
- * dial is through {@link credsForWire}, and the one presentation that does not read the cache
840
- * (the adoption preflight, which presents a fresh CANDIDATE) calls this same function on it.
841
- *
842
- * An unbounded credential (no numeric `exp`) is presentable: bounded lifetimes are the renewal
843
- * seam's concern, and a cred with no expiry has none to be past. */
844
- static presentableCreds(creds, opts) {
845
- const { exp } = credsClaims(creds); // throws on a structurally-unusable file (fail-loud)
846
- if (typeof exp === "number" && exp * 1000 <= Date.now())
847
- throw new Error(opts.renewable
848
- ? "this endpoint's creds have expired and renewal is failing - not presenting the expired credential to the broker; retrying with backoff"
849
- : "this endpoint's creds have expired and it holds no creds source to renew them - replace the credential and rebuild the endpoint (pass a creds FUNCTION for standing renewal)");
850
- return creds;
851
- }
852
- /** The connect attempt's credential getters: what {@link credsForWire} and {@link bearerForWire}
853
- * return, with its expiry recorded as {@link presentedExp}. */
713
+ return this.credentials.bearerForWire();
714
+ }
715
+ /** Forwards to the credentials component's {@link EndpointCredentials.presentCreds}. */
854
716
  presentCreds() {
855
- const creds = this.credsForWire();
856
- this.presentedExp = credsClaims(creds).exp;
857
- return creds;
717
+ return this.credentials.presentCreds();
858
718
  }
719
+ /** Forwards to the credentials component's {@link EndpointCredentials.presentBearer}. */
859
720
  presentBearer() {
860
- const bearer = this.bearerForWire();
861
- this.presentedExp = bearerExpiryMs(bearer) / 1000;
862
- return bearer;
863
- }
864
- /** The cached credential, checked. Handed to nats.js as the authenticator's source on EVERY auth
865
- * mode (renewed or static), so each (re)connect attempt — ours or the library's — re-reads a
866
- * CHECKED value. A refusal throws out of the authenticator, which nats-core turns into a closed
867
- * connection rather than a CONNECT carrying dead material; the endpoint's own supervisor then
868
- * rebuilds on capped backoff, and {@link bindConnection} re-fetches from the source on each of
869
- * those attempts, so a renewal that starts working recovers the endpoint without presenting
870
- * anything expired in the meantime. Deliberately side-effect free: kicking the renewal timer
871
- * from here would retry the source once per dial attempt, which is the flat load on a dead
872
- * broker that {@link RETRY_BACKOFF_CAP_MS} exists to prevent. */
873
- credsForWire() {
874
- if (!this.currentCreds)
875
- throw new Error(this.credsSource
876
- ? "this endpoint has no credential to present yet (the creds source has not returned one) - not dialing without auth material"
877
- : "this endpoint was constructed with an empty creds string - not dialing without auth material (an empty credential is not anonymous access)");
878
- return CotalEndpoint.presentableCreds(this.currentCreds, { renewable: Boolean(this.credsSource) });
721
+ return this.credentials.presentBearer();
879
722
  }
880
723
  /** The credential this endpoint presents on its next connect, checked as {@link credsForWire}
881
724
  * checks it. A second connection under the same identity reads it on every attempt, so it
882
725
  * presents each credential this endpoint adopts and never an expired one. */
883
726
  wireCreds() {
884
- return this.credsForWire();
727
+ return this.credentials.wireCreds();
885
728
  }
886
- /** Refuses a fetched generation there is nothing to renew FROM, so the caller's failure posture
887
- * ({@link CREDS_RETRY_MS}) applies instead of the renewal schedule (issue #1523).
888
- *
889
- * A source that hands back the SAME generation past its own renewal point has not re-signed yet:
890
- * that is a missed remint, not a candidate. Adopting it re-arms from a non-positive delay, which
891
- * {@link armCredsRefresh} floors to 1s, which fetches again, which is the same generation — a 1s
892
- * read loop against a store that is already having a bad day, for the JWT's remaining 25% of life,
893
- * with the 60s backoff that exists for exactly this bypassed because the fetch did not FAIL.
894
- *
895
- * The membership feed's rw-cred renewal already refuses it this way (`membership-feed.ts`,
896
- * `adoptRwCreds`: "the rw source still holds the previous generation past its renewal point");
897
- * this is the same rule on the endpoint's `delivery.creds` seam, so the two renewal paths answer
898
- * a dead source identically.
899
- *
900
- * An ALREADY-EXPIRED generation is refused whatever it is: the delay is non-positive for it too,
901
- * but it is dead rather than merely due, so it is named separately and refused even when the
902
- * source keeps returning a different one. */
903
- static assertRenewableGeneration(candidate, current, delayMs) {
904
- const { exp } = credsClaims(candidate);
905
- if (typeof exp === "number" && exp * 1000 <= Date.now())
906
- throw new Error("the creds source returned an already-expired credential (its `exp` is in the past) - nothing adopted; the renewal owner has not re-signed it, or the store is serving a stale generation");
907
- // Compared by GENERATION, not by envelope. `EndpointOptions.creds` takes opaque file content and
908
- // promises no canonical whitespace: `jwtFromCreds` pads with `\s*` and trims, so a store, editor or
909
- // filesystem round trip that adds a newline re-serves the SAME credential in bytes `===` calls
910
- // different - and the refusal would be skipped for the one case it exists to catch. The envelope
911
- // also carries the nkey seed, which is why `credsFingerprint` hashes the JWT instead.
912
- if (current !== undefined && credsFingerprint(candidate) === credsFingerprint(current) && delayMs <= 0)
913
- throw new Error("the creds source still holds the previous generation past its renewal point (the renewal owner has not re-signed it) - nothing adopted");
914
- }
915
- /** The disposable-preflight connect bound for the EXPLICIT reload proof (D5 class-2 adoption). A
916
- * rogue or unreachable candidate must resolve well UNDER the manager's delivery-admin request
917
- * bound, so this stays a few seconds and never blocks the responder. */
918
- static PREFLIGHT_MS = 4_000;
919
- /** How long the resident wire swap is deferred past the reply on the EXPLICIT reload path. The
920
- * delivery-admin responder rides THIS connection, so `nc.reconnect()` must not run until the
921
- * reply has flushed on the still-live old cred; the old cred stays valid until its exp, so a short
922
- * deferral is safe. */
923
- static RESIDENT_SWAP_DEFER_MS = 250;
924
- /** How long a delivery-admin request read after a reload waits for the resident swap's reconnect.
925
- * nats.js drops a publish made while the connection is down when it redials, so a reply sent
926
- * during the swap is lost and its caller waits out its whole request timeout. Past this bound the
927
- * request is answered anyway, as it was before the gate. */
928
- static RESIDENT_SWAP_GATE_MS = 5_000;
929
- /** The resident swap a reload scheduled, until its connection is back or the gate's bound ends. */
930
- residentSwap;
931
- /** The daemon-side deadline for the WHOLE prove-then-adopt transaction (source fetch + preflight +
932
- * commit), kept strictly BELOW the manager's delivery-admin request bound so a slow or hung hosted
933
- * store returns a structured component failure rather than an ambiguous client timeout, and a late
934
- * fetch can never commit after the caller gave up. */
935
- static RELOAD_DEADLINE_MS = 12_000;
936
- /** Fetch fresh creds from the source, pin their identity to ours, cache them, and arm the next
937
- * refresh at 75% of the new JWT's lifetime. THROWS on fetch/pin failure — the callers decide the
938
- * failure posture (loud-and-retry for the timer, a structured error reply for an explicit
939
- * {@link reloadCreds}). This is the PASSIVE-BACKSTOP fetch; the explicit auditable path
940
- * ({@link reloadCreds}) does its own fetch so it can preflight the candidate on a disposable
941
- * connection BEFORE mutating this live cache. */
942
- async fetchFreshCreds() {
943
- const creds = await this.credsSource();
944
- const id = idFromCreds(creds);
945
- if (id !== this.connId)
946
- throw new Error(`creds source returned identity ${id}, expected ${this.connId} - renewal may not swap the connection's nkey`);
947
- // Before the commit, so a refusal leaves the cache holding the last generation that was renewable
948
- // from (and, on the initial fetch, fails loud rather than dialling with dead material).
949
- const delay = credsRenewalDelayMs(creds);
950
- CotalEndpoint.assertRenewableGeneration(creds, this.currentCreds, delay);
951
- this.currentCreds = creds;
952
- this.armCredsRefresh(delay);
953
- const { iat, exp } = credsClaims(creds);
954
- return { iat, exp };
955
- }
956
- /** Swap the live connection onto the freshest cached cred or bearer with a controlled
957
- * `nc.reconnect()` (nats.js re-evaluates the authenticator per attempt). Swapping now, instead of
958
- * waiting for the broker to close the connection at `exp`, means the wire never carries a
959
- * near-dead JWT and the operator never sees a spurious "authentication expired". After the
960
- * reconnect succeeds, re-arm the expiry fence for the credential now authenticated on the wire. */
961
- async swapConnectionOntoFreshCreds() {
962
- const nc = this.nc;
963
- if (!(nc && !this.stopped))
964
- return;
965
- const overlap = this.overlapOnConnectionRenewal && this.onConnection
966
- ? await this.openRenewalOverlap().catch(() => undefined)
967
- : undefined;
968
- try {
969
- // reconnect() resolves when the disconnect is requested, before subscriptions return.
970
- // A flush started now is sent after those subscriptions, so it resolves only once they
971
- // are on the broker. The overlap stays up until then.
972
- await nc.reconnect().catch(() => { });
973
- if (overlap && !nc.isClosed())
974
- await withDeadline(nc.flush(), 10_000, () => new Error("resident renewal flush did not finish")).catch(() => { });
975
- if (this.nc === nc && !this.stopped)
976
- this.armAuthExpiryReconnectFence(nc);
977
- }
978
- finally {
979
- if (overlap && !overlap.isClosed())
980
- await this.closeWithoutLibraryReconnect(overlap).catch(() => { });
981
- }
729
+ /** Forwards to the credentials component's {@link EndpointCredentials.disableLibraryReconnect}. */
730
+ disableLibraryReconnect(nc) {
731
+ return this.credentials.disableLibraryReconnect(nc);
982
732
  }
983
- /** A second connection whose `onConnection` subscriptions are flushed before the resident
984
- * reconnect. Its inbox is not the resident connection's inbox. A flush that does not finish
985
- * closes it and leaves the caller to reconnect in place. */
986
- async openRenewalOverlap() {
987
- const overlap = await dialerFor(this.servers)({
988
- servers: this.servers,
989
- noAsyncTraces: true,
990
- name: `cotal:${this.card.name}:renewal`,
991
- inboxPrefix: `_INBOX_renew_${randomUUID()}`,
992
- maxReconnectAttempts: 0,
993
- ...authOpts({
994
- token: this.token, user: this.user, pass: this.pass,
995
- creds: this.currentCreds !== undefined || this.credsSource ? () => this.presentCreds() : undefined,
996
- bearer: this.userMode ? () => this.presentBearer() : undefined,
997
- sentinelCreds: this.sentinelCreds, tls: this.tls,
998
- }),
999
- });
1000
- this.ownedConnections.add(overlap);
1001
- try {
1002
- this.onConnection?.(overlap);
1003
- await withDeadline(overlap.flush(), 5_000, () => new Error("renewal overlap flush did not finish"));
1004
- return overlap;
1005
- }
1006
- catch (error) {
1007
- await this.closeWithoutLibraryReconnect(overlap).catch(() => { });
1008
- throw error;
1009
- }
733
+ /** Forwards to the credentials component's {@link EndpointCredentials.closeWithoutLibraryReconnect}. */
734
+ closeWithoutLibraryReconnect(nc) {
735
+ return this.credentials.closeWithoutLibraryReconnect(nc);
1010
736
  }
1011
- /** nats-core keeps its reconnect switch on the protocol handler. This pinned internal shape is the
1012
- * same last-resort surface used by {@link closeFailedBind}; there is no public API for changing the
1013
- * reconnect policy of an existing connection. Disabling it does not disable Cotal self-heal: the
1014
- * `nc.closed()` supervisor below rebuilds the endpoint with freshly checked auth material. */
1015
- disableLibraryReconnect(nc) {
1016
- const protocol = nc.protocol;
1017
- if (protocol?.options)
1018
- protocol.options.reconnect = false;
1019
- }
1020
- /** Close a connection whose library reconnect has already been disabled. `drain()` flushes with a
1021
- * PING and waits for the matching PONG; nats-core only rejects that waiter inside reconnect
1022
- * `prepare()`, so a half-open socket with reconnect=false leaves drain pending until the 2-minute
1023
- * ping interval times out. `close()` tears the transport down without that round-trip, which is
1024
- * the same public path {@link closeFailedBind} already uses when there is no graceful delivery
1025
- * contract left. */
1026
- async closeWithoutLibraryReconnect(nc) {
1027
- if (!nc)
1028
- return;
1029
- this.disableLibraryReconnect(nc);
1030
- await nc.close();
1031
- if (!nc.isClosed())
1032
- throw new Error("endpoint connection closure is unproved; consumer custody must be retained");
1033
- this.ownedConnections.delete(nc);
1034
- }
1035
- /** Disable nats-core reconnect shortly before the JWT authenticated on this wire expires. The small
1036
- * lead makes the policy change precede the broker's expiry close even when both timers wake in the
1037
- * same event-loop turn. A credential adoption does not move this fence until the resident reconnect
1038
- * is requested, so the old wire remains protected during the prove-then-adopt window. */
737
+ /** Forwards to the credentials component's {@link EndpointCredentials.armAuthExpiryReconnectFence}. */
1039
738
  armAuthExpiryReconnectFence(nc) {
1040
- clearTimeout(this.authExpiryReconnectTimer);
1041
- this.authExpiryReconnectTimer = undefined;
1042
- const credsExp = this.currentCreds && credsClaims(this.currentCreds).exp;
1043
- const expiryMs = this.userMode && this.currentBearer
1044
- ? bearerExpiryMs(this.currentBearer)
1045
- : typeof credsExp === "number"
1046
- ? credsExp * 1000
1047
- : undefined;
1048
- if (expiryMs === undefined || this.stopped)
1049
- return;
1050
- // Node fires a delay above 2^31-1 ms (about 24.8 days) after 1 ms, which would disable reconnect
1051
- // at once. A later expiry waits in steps of that bound, and the fence is armed again from there.
1052
- const delay = Math.max(0, expiryMs - Date.now() - 500);
1053
- this.authExpiryReconnectTimer = delay > MAX_TIMER_MS
1054
- ? setTimeout(() => { if (this.nc === nc)
1055
- this.armAuthExpiryReconnectFence(nc); }, MAX_TIMER_MS)
1056
- : setTimeout(() => { if (this.nc === nc)
1057
- this.disableLibraryReconnect(nc); }, delay);
1058
- this.authExpiryReconnectTimer.unref?.();
1059
- }
1060
- /** The connectAndBind PRE-CONNECT fetch: pull the freshest source cred and pin it into
1061
- * {@link currentCreds} so the connect() that immediately follows presents it — that connect IS the
1062
- * proof, so NO preflight and NO live swap here. THROWS when `initial` (no cred to start from), else
1063
- * emits and retries. The LIVE-SWAP paths — the 75% timer {@link renewCredsOnTimer} and the explicit
1064
- * {@link reloadCreds} — preflight the candidate on a disposable connection instead, so they never
1065
- * reconnect the live connection onto an unproven cred. */
1066
- async refreshCreds(initial = false) {
1067
- try {
1068
- await this.fetchFreshCreds();
1069
- }
1070
- catch (e) {
1071
- if (initial)
1072
- throw e;
1073
- this.emitRecoverable(new Error(`creds refresh failed (${e instanceof Error ? e.message : String(e)}) - retrying; this connection dies at its current JWT's expiry if renewal keeps failing`));
1074
- this.armCredsRefresh(CotalEndpoint.CREDS_RETRY_MS);
1075
- }
739
+ return this.credentials.armAuthExpiryReconnectFence(nc);
1076
740
  }
1077
- /** Serializes every prove-then-adopt transaction (the 75% timer and the explicit reload) so a timer
1078
- * tick and an explicit reload can never interleave their fetch/preflight/commit — the design's
1079
- * single-flight requirement. Runs `fn` after any in-flight transaction settles, whatever its
1080
- * outcome; the internal chain never rejects. */
1081
- credsTxn = Promise.resolve();
1082
- runCredsTxn(fn) {
1083
- const counted = async () => {
1084
- this.credsTxnsRunning++;
1085
- try {
1086
- return await fn();
1087
- }
1088
- finally {
1089
- this.credsTxnsRunning--;
1090
- }
1091
- };
1092
- const next = this.credsTxn.then(counted, counted);
1093
- this.credsTxn = next.then(() => undefined, () => undefined);
1094
- return next;
741
+ /** Forwards to the credentials component's {@link EndpointCredentials.refreshCreds}. */
742
+ refreshCreds(initial = false) {
743
+ return this.credentials.refreshCreds(initial);
1095
744
  }
1096
- /** The one PROVE-then-adopt transaction shared by the 75% timer and the explicit reload (run under
1097
- * {@link runCredsTxn}). Fetch (deadline-bounded) → identity-pin → optional `expected` fingerprint →
1098
- * PREFLIGHT the candidate on a disposable connection → fence a late commit against the deadline →
1099
- * commit {@link currentCreds} → arm the next 75% timer. Because currentCreds is written ONLY after
1100
- * the preflight proves broker acceptance, the resident authenticator getter can never present an
1101
- * unproven cred (not even on an incidental reconnect), and a rejected candidate leaves the resident
1102
- * connection untouched on BOTH the timer and explicit paths. THROWS (structured) on any failure. */
1103
- async adoptFreshCreds(opts = {}) {
1104
- // ABSOLUTE deadline, captured at the CALLER's entry (reloadCreds / renewCredsOnTimer) BEFORE the
1105
- // single-flight enqueue, so the queue wait behind an in-flight transaction counts against it. A
1106
- // reload queued behind a hung-store timer tick can never receive a FRESH budget and commit after
1107
- // the renewal owner's request bound already elapsed.
1108
- const deadline = opts.deadline ?? Date.now() + CotalEndpoint.RELOAD_DEADLINE_MS;
1109
- // Fence BEFORE any source I/O: if the queue wait already burned the budget, fail structured now and
1110
- // never touch the store, the preflight, or currentCreds.
1111
- if (Date.now() > deadline)
1112
- throw new Error("reloadCreds: the request deadline elapsed while queued behind another credential transaction; nothing adopted");
1113
- const candidate = await withDeadline(this.credsSource(), deadline - Date.now(), () => new Error("reloadCreds: the creds source did not return before the daemon deadline; nothing adopted"));
1114
- const id = idFromCreds(candidate);
1115
- if (id !== this.connId)
1116
- throw new Error(`creds source returned identity ${id}, expected ${this.connId} - renewal may not swap the connection's nkey`);
1117
- // Non-material message ON PURPOSE: this text flows to the manager's persisted
1118
- // `RenewalRecord.adoption.error`, so neither the observed nor the expected digest may appear.
1119
- if (opts.expected !== undefined && credsFingerprint(candidate) !== opts.expected)
1120
- throw new Error("reloadCreds: re-read credential generation did not match the expected re-signed generation (a different store, or a torn/stale read); nothing adopted");
1121
- // PREFLIGHT = the proof. A disposable connection presenting exactly the candidate BEFORE the live
1122
- // cache is touched; a refused cred throws here, leaving the resident connection untouched.
1123
- // The candidate goes through the SAME checkpoint the resident getter uses: this is the one
1124
- // presentation that does not read the cache, so routing it here is what makes the refusal a
1125
- // property of every path rather than of the cached one. An already-dead re-signed generation is
1126
- // refused locally instead of spending a round trip to be told so, and — because this throws
1127
- // BEFORE the commit below — it can never become the resident connection's next-presented cred.
1128
- const proven = CotalEndpoint.presentableCreds(candidate, { renewable: true });
1129
- const probe = await probeConnect(this.servers, { creds: proven, tls: this.tls, timeoutMs: Math.max(500, Math.min(CotalEndpoint.PREFLIGHT_MS, deadline - Date.now())) });
1130
- if (!probe.ok)
1131
- throw new Error(`reloadCreds: the broker did not accept the re-signed credential (${probe.reason}); nothing adopted`);
1132
- if (Date.now() > deadline)
1133
- throw new Error("reloadCreds: the proof exceeded the daemon deadline; nothing adopted"); // fence a late commit
1134
- // Validate the bounded-window renewal delay BEFORE the commit: credsRenewalDelayMs throws on a cred
1135
- // lacking a numeric `exp`, and that throw must not leave currentCreds flipped to a candidate the
1136
- // authenticator would present on the next reconnect (a post-preflight validation failure is a no-op).
1137
- const delay = credsRenewalDelayMs(candidate);
1138
- CotalEndpoint.assertRenewableGeneration(candidate, this.currentCreds, delay);
1139
- this.currentCreds = candidate;
1140
- this.armCredsRefresh(delay);
1141
- this.emit("creds-adopted", credsClaims(candidate));
1142
- return credsClaims(candidate);
1143
- }
1144
- /** The 75%-of-lifetime renewal timer tick: prove + adopt + swap the LIVE connection. Preflights (it
1145
- * reconnects a live connection, so the candidate must be broker-proven first) and is serialized
1146
- * with the explicit reload. Never throws — a failed renewal logs and retries while the old cred
1147
- * stays live until its expiry. */
1148
- async renewCredsOnTimer() {
1149
- // Deadline captured HERE, before the enqueue, for the same reason as the explicit reload.
1150
- const deadline = Date.now() + CotalEndpoint.RELOAD_DEADLINE_MS;
1151
- try {
1152
- await this.runCredsTxn(() => this.adoptFreshCreds({ deadline }));
1153
- await this.swapConnectionOntoFreshCreds();
1154
- }
1155
- catch (e) {
1156
- this.emitRecoverable(new Error(`creds refresh failed (${e instanceof Error ? e.message : String(e)}) - retrying; this connection dies at its current JWT's expiry if renewal keeps failing`));
1157
- this.armCredsRefresh(CotalEndpoint.CREDS_RETRY_MS);
1158
- }
745
+ /** Forwards to the credentials component's {@link EndpointCredentials.renewCredsOnTimer}. */
746
+ renewCredsOnTimer() {
747
+ return this.credentials.renewCredsOnTimer();
1159
748
  }
1160
749
  /** Fetch, broker-prove and adopt the source credential, then refresh the same connection
1161
750
  * once outgoing mux and named-reply requests are quiet. A busy timeout retains the connection
1162
751
  * and adopted credential. Call again to retry. This does not tear down endpoint bindings.
1163
752
  * A dropped connection that is being re-established carries no request, so it redials now
1164
753
  * instead of after its backoff; the rebuild re-fetches a stale credential from the source. */
1165
- async refreshCredsRequestSafe() {
1166
- if (!this.credsSource)
1167
- throw new Error("credential refresh requires a creds source");
1168
- const nc = this.nc;
1169
- if (!nc && !this.stopped && (this.reconnecting || this.reestablishing))
1170
- return await this.reconnect();
1171
- if (!nc || this.stopped)
1172
- throw new Error("credential refresh requires a running endpoint");
1173
- const deadline = Date.now() + CotalEndpoint.RELOAD_DEADLINE_MS;
1174
- await this.runCredsTxn(async () => {
1175
- await this.adoptFreshCreds({ deadline });
1176
- if (this.nc !== nc || this.stopped)
1177
- throw new Error("endpoint connection changed during credential refresh");
1178
- await requestSafeReconnect(nc, () => this.requestsAwaitingReply.get(nc)?.size ?? 0);
1179
- if (this.nc === nc && !this.stopped)
1180
- this.armAuthExpiryReconnectFence(nc);
1181
- });
754
+ refreshCredsRequestSafe() {
755
+ return this.credentials.refreshCredsRequestSafe();
1182
756
  }
1183
757
  /** EXPLICIT credential reload — the auditable adoption step of D5 class-2 standing renewal (served
1184
758
  * to the renewal owner via the delivery-admin rail). The PROOF-OF-RECORD is a DISPOSABLE PREFLIGHT
@@ -1195,51 +769,12 @@ export class CotalEndpoint extends EventEmitter {
1195
769
  * the resident wire swap is best-effort and self-healing (the 75% timer + the broker's expiry-close),
1196
770
  * NOT witnessed, so the caller must claim broker acceptance, not verified resident reauth. NEVER a
1197
771
  * fingerprint. */
1198
- async reloadCreds(expected) {
1199
- if (!this.credsSource)
1200
- throw new Error("reloadCreds: this endpoint has no creds source (a static cred cannot be renewed in place)");
1201
- // Capture the ABSOLUTE deadline at ENTRY, before enqueue, so a reload queued behind a hung-store
1202
- // 75% timer tick is bounded by the SAME window (queue wait included) and cannot commit/swap after
1203
- // the renewal owner's request bound has already elapsed and it recorded "no responder".
1204
- const deadline = Date.now() + CotalEndpoint.RELOAD_DEADLINE_MS;
1205
- // The prove-then-adopt transaction (fetch + preflight + commit) runs under the single-flight so it
1206
- // cannot interleave with the 75% timer; the wire swap is scheduled by {@link handleDeliveryAdmin}
1207
- // after the aggregate reply (the responder rides this connection).
1208
- const { iat, exp } = await this.runCredsTxn(() => this.adoptFreshCreds({ expected, deadline }));
1209
- return { identity: this.connId, iat, exp };
1210
- }
1211
- /** Arm the resident wire swap for the delivery-admin `reloadCreds` path. Called by
1212
- * {@link handleDeliveryAdmin} ONLY after BOTH component proofs have settled and immediately before
1213
- * the reply is returned+responded — never from inside {@link reloadCreds} while the aggregate is
1214
- * still open, or a slow co-component proof would let `nc.reconnect()` reconnect the admin rail
1215
- * before the reply flushes and silently strand it. The short deferral lets the reply flush on the
1216
- * still-live old cred first. Best-effort — the proof was the preflight; a transient swap failure is
1217
- * retried by the 75% timer and the broker's own expiry-close, both presenting the adopted candidate.
1218
- * Until the swapped connection is back, {@link residentSwap} holds the delivery-admin requests that
1219
- * arrive after this reply. */
772
+ reloadCreds(expected) {
773
+ return this.credentials.reloadCreds(expected);
774
+ }
775
+ /** Forwards to the credentials component's {@link EndpointCredentials.scheduleResidentSwap}. */
1220
776
  scheduleResidentSwap() {
1221
- if (this.stopped)
1222
- return;
1223
- const swap = new Promise((resolve) => { setTimeout(resolve, CotalEndpoint.RESIDENT_SWAP_DEFER_MS).unref?.(); })
1224
- .then(async () => {
1225
- const back = this.transportBack(CotalEndpoint.RESIDENT_SWAP_GATE_MS);
1226
- await this.swapConnectionOntoFreshCreds();
1227
- await back;
1228
- })
1229
- .finally(() => { if (this.residentSwap === swap)
1230
- this.residentSwap = undefined; });
1231
- this.residentSwap = swap;
1232
- }
1233
- /** Resolve when this endpoint reports its transport connected again, or after `ms`. */
1234
- transportBack(ms) {
1235
- return new Promise((resolve) => {
1236
- const done = () => { clearTimeout(timer); this.off("transport", seen); resolve(); };
1237
- const seen = (state) => { if (state.connected)
1238
- done(); };
1239
- const timer = setTimeout(done, ms);
1240
- timer.unref?.();
1241
- this.on("transport", seen);
1242
- });
777
+ return this.credentials.scheduleResidentSwap();
1243
778
  }
1244
779
  armCredsRefresh(delayMs) {
1245
780
  if (this.stopped)
@@ -4959,621 +4494,4 @@ export class CotalEndpoint extends EventEmitter {
4959
4494
  return this.presence.sweep();
4960
4495
  }
4961
4496
  }
4962
- /** A usable delivery-message id (#624): a string, possibly empty (the never-a-key case), but
4963
- * never absent and never a non-string. An absent or non-string id is a malformed envelope under
4964
- * SPEC sec 5; each delivery pump handles it per its own class (durable term, live drop, history
4965
- * skip) so it never reaches the receiver's id-keyed machinery as `undefined`. */
4966
- function isUsableMessageId(id) {
4967
- return typeof id === "string";
4968
- }
4969
- /** Map an authenticated parsed-subject kind to the message class surfaced to "message" listeners.
4970
- * Throws on `ctl` (control-plane is request/reply, never a "message") — per repo convention, no
4971
- * silent default: an unexpected delivering kind is a bug, not something to swallow. */
4972
- function kindFromParsed(kind) {
4973
- switch (kind) {
4974
- case "chat":
4975
- return "channel";
4976
- case "inst":
4977
- return "dm";
4978
- case "svc":
4979
- return "anycast";
4980
- default:
4981
- throw new Error(`cannot derive a message kind from subject kind "${kind}"`);
4982
- }
4983
- }
4984
- /** SPEC §5 on receive: a delivery comes from the principal its subject names. The payload is an
4985
- * object whose `from.id` is the subject's sender, and the subject's owner is a real principal, not
4986
- * an old-shape alias. Every receive path asks this one predicate. What a path does with a refusal
4987
- * (drop, skip, ack, term or reject) and its own extra checks (a usable id, its own echo) stay with
4988
- * the path. */
4989
- export function isFromSubjectSender(msg, parsed) {
4990
- return isRecord(msg) && isRecord(msg.from) && msg.from.id === parsed.sender && isPrincipalOwnerToken(parsed.owner);
4991
- }
4992
- /** Routing fields in the envelope are advisory. The broker forge-locks sender (and for DMs,
4993
- * recipient) into the subject. Callers MUST already have passed {@link isFromSubjectSender}
4994
- * (SPEC §5). This derives the remaining
4995
- * routing tokens from the subject for rows that survived — it does not rewrite a mismatched
4996
- * `from.id`. Live tails, channel backfill, and channel recall skip the mismatch; history
4997
- * does the same (#388). The row's other fields pass through UNTOUCHED, so what the caller's
4998
- * row type already verified stays verified (#1413). */
4999
- function authenticatedMessage(msg, parsed) {
5000
- if (parsed.kind === "chat" || parsed.kind === "evp")
5001
- return authenticatedChannelMessage(msg, parsed.rest);
5002
- if (parsed.kind === "inst")
5003
- return authenticatedDmMessage(msg, parsed.rest);
5004
- if (parsed.kind === "svc")
5005
- return authenticatedAnycastMessage(msg, parsed.rest);
5006
- return msg;
5007
- }
5008
- function authenticatedDmMessage(msg, to) {
5009
- if (msg.to === to && msg.channel === undefined && msg.toService === undefined)
5010
- return msg;
5011
- const { channel: _channel, toService: _toService, ...base } = msg;
5012
- return { ...base, to };
5013
- }
5014
- function authenticatedAnycastMessage(msg, toService) {
5015
- if (msg.toService === toService && msg.to === undefined && msg.channel === undefined)
5016
- return msg;
5017
- const { to: _to, channel: _channel, ...base } = msg;
5018
- return { ...base, toService };
5019
- }
5020
- /** A DM-only copy's delivery. An ack, nak or in-progress signal on a closed connection is refused
5021
- * with a throw instead of being dropped silently: the copy stays unacked and the broker redelivers it. */
5022
- function dmOnlyDelivery(m, ackWaitMs, nc) {
5023
- const open = (what) => {
5024
- if (!nc || nc.isClosed())
5025
- throw new Error(`DM-only ${what} refused: the connection that delivered this copy is closed; the broker will redeliver it`);
5026
- };
5027
- return {
5028
- ack: () => { open("ack"); m.ack(); },
5029
- nak: () => { open("nak"); m.nak(); },
5030
- durable: true,
5031
- redelivery: { deliveryCount: m.info.deliveryCount, ackWaitMs, working: () => { open("in-progress signal"); m.working(); } },
5032
- };
5033
- }
5034
- /** History drain keeps `m.json()` and used to throw the subject away. SPEC §5: on receive, verify
5035
- * `from.id` equals the subject sender; on mismatch, a missing `from`, or an unparseable delivery
5036
- * subject, reject and never surface. Fail closed on shape too: a stored JSON `null` or a truthy
5037
- * non-object `from` must not throw mid-array. Do not echo-drop `from.id === this.card.id`:
5038
- * god-view history must include the viewer's own sends. */
5039
- function historyMessageFromDelivery(m) {
5040
- let raw;
5041
- try {
5042
- raw = m.json();
5043
- }
5044
- catch {
5045
- return undefined;
5046
- }
5047
- if (!isHistoryDrainEnvelope(raw))
5048
- return undefined;
5049
- if (!isVerifiedHistoryRow(raw))
5050
- return undefined;
5051
- const parsed = parseSubject(m.subject);
5052
- if (!parsed || !isFromSubjectSender(raw, parsed))
5053
- return undefined;
5054
- return authenticatedMessage(raw, parsed);
5055
- }
5056
- /** The members `HistoryMessage` promises beyond the drain envelope (#1413): a full
5057
- * `EndpointRef` (`from.name`, and `from.role` only when a string), a finite `ts`, a string
5058
- * `space`, `parts` the drain could read, and the optional members in their promised shape
5059
- * when present. Every field the PUBLIC row type promises is checked here, before the row is
5060
- * returned. A row missing one is dropped, never returned with that member silently
5061
- * `undefined` under the full type — a consumer reading `msg.ts`, `msg.space`, `msg.parts`
5062
- * or `msg.from.name` must not be able to reach one that was never there. Nothing is invented
5063
- * for an absent field.
5064
- *
5065
- * `parts` is held to READABLE, not to `isMessagePart`: every member must be an object with a
5066
- * string `kind` (so `partsToText` can read `part.kind` without throwing), but a keyless
5067
- * `{kind:"data"}` row from a pre-#1404 producer is not dropped — history must surface it.
5068
- * `mentions`, `replyTo`, and `contextId` keep exactly their `CotalMessage` shapes when
5069
- * present: an array of strings, a string, a string. */
5070
- function isVerifiedHistoryRow(row) {
5071
- if (typeof row.from.name !== "string")
5072
- return false;
5073
- if (row.from.role !== undefined && typeof row.from.role !== "string")
5074
- return false;
5075
- if (typeof row.ts !== "number" || !Number.isFinite(row.ts))
5076
- return false;
5077
- if (typeof row.space !== "string")
5078
- return false;
5079
- if (!Array.isArray(row.parts) || !row.parts.every(isReadableMessagePart))
5080
- return false;
5081
- if (row.mentions !== undefined &&
5082
- (!Array.isArray(row.mentions) || !row.mentions.every((name) => typeof name === "string")))
5083
- return false;
5084
- if (row.replyTo !== undefined && typeof row.replyTo !== "string")
5085
- return false;
5086
- if (row.contextId !== undefined && typeof row.contextId !== "string")
5087
- return false;
5088
- return true;
5089
- }
5090
- /** A part `partsToText` can read without throwing: an object with a string `kind` (#1413).
5091
- * Deliberately weaker than `isMessagePart` — a keyless `{kind:"data"}` part passes here —
5092
- * because history must surface rows a pre-#1404 producer wrote, not drop them. */
5093
- function isReadableMessagePart(value) {
5094
- return isRecord(value) && typeof value.kind === "string";
5095
- }
5096
- /**
5097
- * Narrow enough for the type checker and for fail-closed history: object envelope, usable `id`,
5098
- * object `from`. That is what lets `authenticatedMessage` take the row without a cast.
5099
- *
5100
- * Does NOT verify SPEC §5 message shape. It does not require a string `from.id` (the SPEC §5
5101
- * comparison still rejects a mismatch) or exactly one route key. The members the PUBLIC
5102
- * history row promises beyond this envelope — a full EndpointRef `from` (`name`/`role`), a
5103
- * finite `ts`, a string `space` — are checked by {@link isVerifiedHistoryRow} before the row
5104
- * is returned (#1413). Well-formed `parts` still belong to `isCotalMessage` (Plane-3), and
5105
- * history must not use that guard: a publisher now REFUSES a `data` part carrying a non-JSON
5106
- * value, but a keyless `{kind:"data"}` row from a pre-fix producer can still sit in a stream,
5107
- * and history must surface it rather than drop it.
5108
- */
5109
- function isHistoryDrainEnvelope(value) {
5110
- return isRecord(value) && isUsableMessageId(value.id) && isRecord(value.from);
5111
- }
5112
- function authOpts(a) {
5113
- const tls = a.tls ? {} : undefined;
5114
- // USER MODE: present the shared auth-account sentinel creds AND the user bearer as `auth_token` (an
5115
- // authenticator ARRAY — nats.js merges them into one CONNECT). The connect lands in the callout
5116
- // account, which validates the bearer and re-binds the client into the data account with a scoped JWT.
5117
- if (a.bearer) {
5118
- if (a.creds || a.token || a.user || a.pass)
5119
- throw new Error("bearer (user-mode auth) is mutually exclusive with creds/token/user/pass");
5120
- if (!a.sentinelCreds)
5121
- throw new Error("user-mode bearer requires sentinelCreds");
5122
- return {
5123
- authenticator: [nativeCredsAuthenticator(a.sentinelCreds), tokenAuthenticator(a.bearer)],
5124
- tls,
5125
- };
5126
- }
5127
- // creds (JWT/nkey) are mutually exclusive with token/user/pass — reject rather than
5128
- // silently pick one, so a misconfigured caller fails loud.
5129
- if (a.creds) {
5130
- if (a.token || a.user || a.pass)
5131
- throw new Error("creds are mutually exclusive with token/user/pass auth");
5132
- const creds = a.creds;
5133
- // A getter re-wraps per (re)connect attempt so each attempt signs with the freshest cred;
5134
- // nats.js invokes the authenticator function on every attempt, including internal reconnects.
5135
- const authenticator = (nonce) => {
5136
- const presented = typeof creds === "function" ? creds() : creds;
5137
- const authenticated = nativeCredsAuthenticator(presented)(nonce);
5138
- a.onCreds?.(presented);
5139
- return authenticated;
5140
- };
5141
- return { authenticator, tls };
5142
- }
5143
- return { token: a.token, user: a.user, pass: a.pass, tls };
5144
- }
5145
- /** The bearer's `exp` as epoch ms — what the refresh schedule keys on. A bearer without a numeric
5146
- * `exp` is structurally unusable for a refreshing endpoint (fail-loud, like the principal decode). */
5147
- function bearerExpiryMs(bearer) {
5148
- return bearerLifetimeMs(bearer, 0).expiresAtMs;
5149
- }
5150
- /** The bearer's lifetime as epoch ms: `iat` to `exp`, starting at `adoptedAtMs` when it carries no
5151
- * `iat`. */
5152
- function bearerLifetimeMs(bearer, adoptedAtMs) {
5153
- const payload = bearer.split(".")[1];
5154
- if (!payload)
5155
- throw new Error("user-mode bearer is not a JWT (no payload segment)");
5156
- let claims;
5157
- try {
5158
- claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
5159
- }
5160
- catch {
5161
- throw new Error("user-mode bearer payload is not valid base64url JSON");
5162
- }
5163
- if (typeof claims.exp !== "number")
5164
- throw new Error("user-mode bearer is missing a numeric exp claim");
5165
- const expiresAtMs = claims.exp * 1000;
5166
- return { issuedAtMs: Math.min(typeof claims.iat === "number" ? claims.iat * 1000 : adoptedAtMs, expiresAtMs), expiresAtMs };
5167
- }
5168
- /** Past this point a held bearer is overdue: its renewal should already have replaced it. */
5169
- function bearerRenewalDeadlineMs(bearer, adoptedAtMs) {
5170
- const { issuedAtMs, expiresAtMs } = bearerLifetimeMs(bearer, adoptedAtMs);
5171
- return renewalDeadlineMs(issuedAtMs, expiresAtMs);
5172
- }
5173
- /** A refusal already surfaced once for this outage. The rebuild loop retries it without a notice,
5174
- * so an endpoint that cannot renew shows one status line rather than one per attempt. */
5175
- class RepeatedRefusal extends Error {
5176
- }
5177
- /** Decode the owner+actor PRINCIPAL from a user bearer WITHOUT verifying it — the client trusts its own
5178
- * bearer only to build its subjects; the broker's minted grant (from the callout, which DOES verify the
5179
- * bearer) is the real boundary, so a client that lied to itself would just be denied. Per the token
5180
- * claim semantics the OWNER is the JWT `sub` (`act.owner` merely restates it) and the ACTOR is
5181
- * `act.actor`. Throws on a structurally-unusable bearer (fail-loud). */
5182
- function decodeBearerPrincipal(bearer) {
5183
- const payload = bearer.split(".")[1];
5184
- if (!payload)
5185
- throw new Error("user-mode bearer is not a JWT (no payload segment)");
5186
- let claims;
5187
- try {
5188
- claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
5189
- }
5190
- catch {
5191
- throw new Error("user-mode bearer payload is not valid base64url JSON");
5192
- }
5193
- const owner = claims.sub, actor = claims.act?.actor;
5194
- if (typeof owner !== "string" || typeof actor !== "string")
5195
- throw new Error("user-mode bearer is missing a string sub (owner) / act.actor claim");
5196
- return { owner, actor };
5197
- }
5198
- /** Turn a raw async-status error into one whose message says *why* — a permission
5199
- * violation looks like absence unless it's named as a denial. */
5200
- function describeStatusError(err) {
5201
- if (err instanceof PermissionViolationError) {
5202
- return new Error(`NATS permission denied: cannot ${err.operation} "${err.subject}" - check this ` +
5203
- `endpoint's ACLs (a denied peer looks "absent" rather than blocked)`, { cause: err });
5204
- }
5205
- return err;
5206
- }
5207
- /** The ordered consumer behind a KV watch, which nats.js keeps on the iterator and the KV types hide. */
5208
- function kvWatchConsumer(iter) {
5209
- const consumer = iter._data;
5210
- if (!consumer)
5211
- throw new Error("KV watch carries no consumer - the pinned nats.js changed shape");
5212
- return consumer;
5213
- }
5214
- /** True ONLY for a denial on a **publish** — the single case that proves the message was never
5215
- * ACCEPTED or stored. (Not "never reached the server": the server necessarily received enough of
5216
- * it to reject it. The distinction matters precisely here, because this helper exists to separate
5217
- * provably-not-stored from possibly-stored, and the looser phrasing overstates the very thing
5218
- * being measured.) {@link isPermissionDenied} deliberately does not look at the operation: it exists to
5219
- * separate "denied" from "service down", and that answer is the same either way. The operation
5220
- * matters enormously to a caller that reports *delivery*, because a JetStream publish is
5221
- * request/PubAck and the subscription half is the reply inbox — a denial THERE rejects
5222
- * `js.publish()` while the stream may already hold the message. Verified against a live broker: a
5223
- * user allowed to publish but denied its `_INBOX` subscription got
5224
- * `Permissions Violation for Subscription to "_INBOX.….*"` back from `js.publish()`, and an
5225
- * unrestricted observer then read `messages: 1` off the stream.
5226
- *
5227
- * Note what is deliberately NOT accepted: the untyped text fallback above. A permission-shaped
5228
- * message string carries no operation, so it cannot prove non-delivery, and guessing "publish"
5229
- * from wording would reintroduce exactly the false certainty this exists to prevent. Anything not
5230
- * provably a publish denial is unknown, and a caller reporting delivery must fail toward
5231
- * "I could not confirm" rather than toward "it did not happen" — the costly mistake is telling
5232
- * someone to re-send a message that was in fact stored. */
5233
- export function isPublishPermissionDenied(e) {
5234
- const typed = e instanceof PermissionViolationError
5235
- ? e
5236
- : e?.cause instanceof PermissionViolationError
5237
- ? (e.cause)
5238
- : undefined;
5239
- return typed?.operation === "publish";
5240
- }
5241
- /** Whether a server list dials over websocket: the FIRST entry's scheme decides (one list, one
5242
- * transport — a mixed tcp+ws list would race two transports over one identity). */
5243
- export function wsServers(servers) {
5244
- return /^wss?:\/\//i.test((servers.split(",")[0] ?? "").trim());
5245
- }
5246
- /** Default probe budget by TRANSPORT. 1s was tuned for the loopback/LAN TCP brokers every local
5247
- * probe dials; a ws(s) broker is by definition published through an HTTPS edge (CDN tunnel,
5248
- * reverse proxy), where TLS + upgrade + INFO + the auth round-trip routinely exceeds 1s cold —
5249
- * measured ~60% spurious "not reachable" against a Cloudflare-fronted broker. Callers passing an
5250
- * explicit `timeoutMs` are untouched.
5251
- *
5252
- * EXPORTED because a caller that judges a probe by WHEN it answered has to compare against the
5253
- * deadline this function actually handed the probe. The delivery watchdog does exactly that, and
5254
- * hardcoding 1000 there silently misread every ws broker: honest refusals arrive at 2-5s, past a
5255
- * budget that was never theirs, and would be classified as this process's starvation rather than
5256
- * the server's refusal. The budget and the judgment must come from one place. */
5257
- export function defaultProbeTimeoutMs(servers) {
5258
- return wsServers(servers) ? 5000 : 1000;
5259
- }
5260
- /** Pick the dial function by SCHEME: `ws://`/`wss://` servers go through nats-core's
5261
- * `wsconnect` (the websocket transport - e.g. a broker published through an HTTPS edge at
5262
- * `wss://host/path`), everything else through the TCP transport. The websocket dial OWNS its
5263
- * transport options: a required TLS connection refuses any `ws://` target before dialing.
5264
- * `wss://` performs TLS itself, and the w3c transport refuses a `tls` block outright
5265
- * ("'tls' is not configurable"), so the block is removed after that check.
5266
- * A TCP dial that requires TLS to one IP address names that address as the host its certificate
5267
- * must cover (see {@link withDialedTlsHost}). */
5268
- export function dialerFor(servers) {
5269
- if (!wsServers(servers))
5270
- return ((opts) => connect(withDialedTlsHost(servers, opts)));
5271
- return ((opts) => {
5272
- const { tls, ...rest } = (opts ?? {});
5273
- const targets = Array.isArray(rest.servers) ? rest.servers : String(rest.servers ?? servers).split(",");
5274
- if (tls && targets.some((target) => !/^wss:\/\//i.test(String(target).trim())))
5275
- return Promise.reject(new Error("TLS-required WebSocket connections must use wss:// for every server"));
5276
- return wsconnect(rest);
5277
- });
5278
- }
5279
- /** `opts` for a dial to `servers`, with the IP address it names as the host a TLS certificate must
5280
- * cover when the dial requires TLS: a `tls` block, or a `tls://` address. The TCP transport upgrades
5281
- * to TLS with no server name for an IP, and Node then checks the certificate against "localhost":
5282
- * a certificate for the dialed address alone is refused, and one naming localhost passes for any
5283
- * address. A dial that does not require TLS keeps its options, because a `tls` block refuses a
5284
- * plaintext broker, and so does a list of several servers, whose one host the options cannot name. */
5285
- function withDialedTlsHost(servers, opts) {
5286
- const urls = servers.split(",").map((url) => url.trim()).filter(Boolean);
5287
- const tls = opts?.tls;
5288
- if (urls.length !== 1 || tls === null || tls === undefined && !/^tls:\/\//i.test(urls[0]))
5289
- return opts;
5290
- let host;
5291
- try {
5292
- ({ host } = hostPort(urls[0]));
5293
- }
5294
- catch {
5295
- return opts;
5296
- }
5297
- // Node checks an upgraded socket's certificate against `host` when no server name is set.
5298
- return isIP(host) ? { ...opts, tls: { host, ...tls } } : opts;
5299
- }
5300
- /** Parse a NATS server URL (`nats://host:port`, `host:port`, a bare host, or a comma list — the
5301
- * first entry wins) into a host+port for {@link tcpInfoProbe}. Defaults the port to 4222. */
5302
- function hostPort(server) {
5303
- const raw = (server.split(",")[0] ?? "").trim();
5304
- const scheme = raw.match(/^([a-z][a-z0-9+.-]*):\/\//i)?.[1]?.toLowerCase();
5305
- const first = raw.replace(/^[a-z][a-z0-9+.-]*:\/\//i, ""); // strip scheme
5306
- const u = new URL(`http://${first}`); // http:// so .hostname/.port resolve (incl. bracketed IPv6)
5307
- // A websocket broker rides the web's ports, not NATS's: `wss://host/path` reaches TCP 443.
5308
- const fallback = scheme === "wss" ? 443 : scheme === "ws" ? 80 : 4222;
5309
- return { host: u.hostname, port: u.port ? Number(u.port) : fallback };
5310
- }
5311
- /** Silent credless liveness probe. Opens a plain TCP connection and confirms a NATS server is there
5312
- * by reading its UNPROMPTED `INFO {…}` greeting — which the server sends on accept, BEFORE the
5313
- * client's CONNECT/auth (per the NATS client protocol) — then closes immediately without
5314
- * authenticating. Since it never sends CONNECT, an auth broker has nothing to reject, so this emits
5315
- * NO broker-side auth-error/auth-timeout log line (unlike a credless `connect()`, which an auth
5316
- * broker rejects and logs). It is a *plaintext NATS* liveness check only:
5317
- * • a TLS-first (`handshake_first`, NATS ≥ 2.10.4) listener sends its TLS handshake before INFO,
5318
- * so the read won't match → returns false (a documented false-negative for that broker config);
5319
- * • a non-NATS listener never sends a valid `INFO {` → also false, and a silent one resolves
5320
- * `"silent"` (we require the real greeting, never "any open port is reachable").
5321
- * Closes well within the server's ~1s authorization timeout, so it cannot trip a timeout log.
5322
- * A live server resolves to what its greeting said about auth. A peer that accepted the connection
5323
- * and sent no full line before the deadline, as a stopped or overloaded broker does, resolves
5324
- * `"silent"`; anything else resolves `false`. */
5325
- function tcpInfoProbe(server, timeoutMs) {
5326
- return new Promise((resolve) => {
5327
- let socket;
5328
- let done = false;
5329
- let connected = false;
5330
- const finish = (live) => {
5331
- if (done)
5332
- return;
5333
- done = true;
5334
- try {
5335
- socket?.destroy();
5336
- }
5337
- catch { /* already gone */ }
5338
- resolve(live);
5339
- };
5340
- let host, port;
5341
- try {
5342
- ({ host, port } = hostPort(server));
5343
- }
5344
- catch {
5345
- return resolve(false);
5346
- }
5347
- socket = createConnection({ host, port });
5348
- socket.setTimeout(timeoutMs);
5349
- let buf = "";
5350
- socket.on("data", (chunk) => {
5351
- buf += chunk.toString("utf8");
5352
- const nl = buf.indexOf("\r\n");
5353
- if (nl === -1) {
5354
- if (buf.length > 4096)
5355
- finish(false);
5356
- return;
5357
- } // no real INFO line is 4KB+
5358
- const line = buf.slice(0, nl);
5359
- const brace = line.indexOf("{"); // greeting is `INFO {json}` (the server appends a trailing space)
5360
- if (!/^INFO\b/.test(line) || brace === -1)
5361
- return finish(false); // not NATS (incl. a TLS-first handshake)
5362
- try {
5363
- finish({ authRequired: JSON.parse(line.slice(brace))?.auth_required === true });
5364
- } // require a real INFO greeting, not arbitrary bytes
5365
- catch {
5366
- finish(false);
5367
- }
5368
- });
5369
- socket.on("connect", () => { connected = true; });
5370
- socket.on("timeout", () => finish(connected ? "silent" : false));
5371
- socket.on("error", () => finish(false)); // refused / reset / DNS failure
5372
- socket.on("close", () => finish(false)); // closed before a full INFO line arrived
5373
- });
5374
- }
5375
- /** Bounded TCP reachability on a socket we OWN: does a handshake to `server` complete within
5376
- * `timeoutMs`? Deliberately narrower than {@link tcpInfoProbe} — it asks only whether the
5377
- * transport can be reached, never whether NATS is speaking there, so the TLS-first listener that
5378
- * `tcpInfoProbe` reports false for still passes this gate and goes on to a real connect.
5379
- *
5380
- * It exists because `connect()` cannot be trusted to release a connection it never established.
5381
- * `@nats-io/transport-node`'s `NodeTransport.dial()` keeps its socket in a local until the
5382
- * handshake resolves (`this.socket = await this.dial(hp)`), so `this.socket` is STILL UNDEFINED
5383
- * when the client's own connect timeout wins the race in `protocol.ts`'s `dial` and the catch
5384
- * calls `transport.close()` — whose teardown is `this.socket?.destroy()`, i.e. a destroy of
5385
- * nothing. Against an address that BLACKHOLES (SYN unanswered) rather than REFUSES (RST), the
5386
- * socket is orphaned in libuv until the OS SYN timeout, and the process cannot exit for minutes
5387
- * after the probe already returned its answer. That is issue #389, and it is upstream: nothing a
5388
- * caller passes (`reconnect: false`, `timeout`) reaches the orphan. Our socket, our `destroy()`,
5389
- * on every exit path — never an `unref`/force-exit, which would hide the symptom and a future
5390
- * real hang with it. A second orphan case (#2156) needs a greeting, not just a handshake, so it is
5391
- * gated by {@link tcpInfoProbe} instead wherever the dial will be plaintext. */
5392
- function tcpDialable(server, timeoutMs) {
5393
- return new Promise((resolve) => {
5394
- let socket;
5395
- let done = false;
5396
- const finish = (dialable) => {
5397
- if (done)
5398
- return;
5399
- done = true;
5400
- try {
5401
- socket?.destroy();
5402
- }
5403
- catch { /* already gone */ }
5404
- resolve(dialable);
5405
- };
5406
- let host, port;
5407
- try {
5408
- ({ host, port } = hostPort(server));
5409
- }
5410
- catch {
5411
- return resolve(false);
5412
- }
5413
- socket = createConnection({ host, port });
5414
- socket.setTimeout(timeoutMs);
5415
- socket.on("connect", () => finish(true));
5416
- socket.on("timeout", () => finish(false)); // blackhole: SYN unanswered inside our deadline
5417
- socket.on("error", () => finish(false)); // refused / reset / DNS failure
5418
- socket.on("close", () => finish(false));
5419
- });
5420
- }
5421
- /** Whether a failed connect was the server refusing these credentials: a server answered, so it is
5422
- * up. The same errors {@link isReachable} reads as up after its own authenticated connect. */
5423
- export function isAuthRejection(e) {
5424
- return e instanceof AuthorizationError || e instanceof UserAuthenticationExpiredError;
5425
- }
5426
- /** The wait a credential source asked for with a numeric `retryAfterSeconds` on its error, in
5427
- * milliseconds, or 0. */
5428
- function retryAfterMs(e) {
5429
- const seconds = e?.retryAfterSeconds;
5430
- return typeof seconds === "number" && Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : 0;
5431
- }
5432
- /** Whether a NATS server is *running* at `servers`. With NO creds this is a SILENT plaintext
5433
- * liveness check ({@link tcpInfoProbe}): it reads the server's pre-auth `INFO` greeting and closes
5434
- * WITHOUT authenticating, so a live broker (open OR auth — INFO precedes auth) returns true while
5435
- * emitting no broker auth-error log. It may return false for a TLS-first listener — the credless
5436
- * probe is plaintext-only. With creds/token/tls supplied it is instead the AUTHORITATIVE identity
5437
- * check: a real authenticated connect, true on success AND on an auth rejection (a server that
5438
- * refuses these creds is still up — so the caller surfaces the real auth failure, and `up` won't
5439
- * start a duplicate on the bound port). Only a genuine connection failure (refused/timeout) is false. */
5440
- export async function isReachable(servers = DEFAULT_SERVER, opts = {}) {
5441
- const timeoutMs = opts.timeoutMs ?? defaultProbeTimeoutMs(servers);
5442
- if (!opts.creds && !opts.token && !opts.user && !opts.pass && !opts.tls) {
5443
- // A websocket broker rides an HTTPS edge: the plaintext INFO probe reads TLS bytes and
5444
- // declares a perfectly live broker down (which then blocks spawn/connect with a wrong
5445
- // remedy). Dial the ws transport credless instead — an auth broker REJECTING the bare
5446
- // connect still proves it is there, the same reading the authed branch below gives its
5447
- // catch. Costs one broker-side auth-error log line per probe, which the INFO probe was
5448
- // designed to avoid; on a ws broker there is no silent alternative.
5449
- if (wsServers(servers)) {
5450
- try {
5451
- const nc = await dialerFor(servers)({ servers, timeout: timeoutMs, reconnect: false, maxReconnectAttempts: 0 });
5452
- await nc.close();
5453
- return true;
5454
- }
5455
- catch (e) {
5456
- return e instanceof AuthorizationError || e instanceof UserAuthenticationExpiredError;
5457
- }
5458
- }
5459
- return typeof (await tcpInfoProbe(servers, timeoutMs)) === "object";
5460
- }
5461
- // The credless branch above already owns its socket. This one reaches `connect()`, so it carries
5462
- // the same orphaned-socket defects probeConnect did (#389, and the slow-greeting case #2156) and
5463
- // takes the same gate choice: reach the address on a socket we own first, requiring the NATS
5464
- // greeting for a plaintext dial (the upstream transport orphans a socket whose handshake
5465
- // completed but whose greeting came late) and only the handshake for a TLS-required or websocket
5466
- // dial (no plaintext greeting to read), then give `connect()` the remainder of the budget its own
5467
- // timeout always covered. A gate failure is a genuine connection failure, which is exactly the
5468
- // `false` the catch below already returns for one — an auth rejection cannot reach us from an
5469
- // address that never completed a handshake.
5470
- const started = Date.now();
5471
- const gate = opts.tls || wsServers(servers) ? tcpDialable : tcpInfoProbe;
5472
- const reached = await gate(servers, timeoutMs);
5473
- if (!reached || reached === "silent")
5474
- return false;
5475
- try {
5476
- const nc = await dialerFor(servers)({
5477
- servers,
5478
- timeout: Math.max(1, timeoutMs - (Date.now() - started)),
5479
- reconnect: false,
5480
- maxReconnectAttempts: 0,
5481
- ...authOpts(opts),
5482
- });
5483
- await nc.close();
5484
- return true;
5485
- }
5486
- catch (e) {
5487
- return e instanceof AuthorizationError || e instanceof UserAuthenticationExpiredError;
5488
- }
5489
- }
5490
- /** Like {@link isReachable}, but distinguishes "up but won't take these creds" from "nothing there".
5491
- * `spawn` needs the difference: auth-required → name the trust dir + next step; unreachable → the
5492
- * mesh is down (prune the stale entry, tell the user to `cotal up`). Pass `creds` to confirm a
5493
- * specific identity is accepted (`ok`); omit them to probe mere liveness (an auth broker answers
5494
- * `auth-required`, which still proves it's up). */
5495
- export async function probeConnect(server = DEFAULT_SERVER, opts = {}) {
5496
- const timeoutMs = opts.timeoutMs ?? defaultProbeTimeoutMs(server);
5497
- const started = Date.now();
5498
- // Reach the address on a socket we own BEFORE handing it to `connect()`, which orphans the
5499
- // connection it never established (see {@link tcpDialable} for the upstream mechanism, #389,
5500
- // and {@link tcpInfoProbe} for the second orphan case below, #2156). For a plaintext dial the
5501
- // gate must see the server's NATS greeting, not just the handshake: `connect()`'s own timeout
5502
- // can fire while it is still waiting on that greeting, and the upstream transport only destroys
5503
- // a socket whose handshake never completed, not one whose greeting came late (`_closed`'s guard
5504
- // on `connected`, which is set only after the greeting is read) — so `tcpInfoProbe` (which owns
5505
- // its socket and requires the greeting) is the gate there, while a TLS-required or websocket
5506
- // dial has no plaintext greeting to read and keeps the handshake-only `tcpDialable` gate. This
5507
- // cannot change any verdict: every address that gets past here had to complete a TCP handshake
5508
- // for `connect()` to have gotten anywhere either, and a gate failure is routed through the SAME
5509
- // classification the catch uses — so a locally-dead cred is still `stale-auth` and not silently
5510
- // downgraded to `unreachable` by the address being dark. The cost is one extra handshake (and,
5511
- // off TLS/ws, one extra greeting read) on the reachable path; the deadline below is the
5512
- // REMAINDER of the budget, because `connect()`'s own `timeout` always covered its handshake too.
5513
- const gate = opts.tls || wsServers(server) ? tcpDialable : tcpInfoProbe;
5514
- const greeting = await gate(server, timeoutMs);
5515
- if (!greeting)
5516
- return classifyProbeFailure(undefined, opts);
5517
- // A peer that took the connection and never greeted is there but not answering, as a stopped or
5518
- // overloaded broker is. That is the same latency verdict as a dial that ran out of its budget.
5519
- if (greeting === "silent")
5520
- return classifyProbeFailure(undefined, opts, false, "timeout");
5521
- try {
5522
- const nc = await dialerFor(server)({
5523
- servers: server,
5524
- timeout: Math.max(1, timeoutMs - (Date.now() - started)),
5525
- reconnect: false,
5526
- maxReconnectAttempts: 0,
5527
- ...authOpts(opts),
5528
- });
5529
- await nc.close();
5530
- return { ok: true };
5531
- }
5532
- catch (e) {
5533
- return classifyProbeFailure(e, opts, greeting !== true && greeting.authRequired);
5534
- }
5535
- }
5536
- /** Why a {@link probeConnect} attempt did not end in `ok`. Shared by the pre-connect reachability
5537
- * gate and the connect catch so both classify identically — the gate must never turn a diagnosable
5538
- * credential death into a bare `unreachable` just because the address went dark.
5539
- *
5540
- * A presented cred that is PROVABLY expired by its own JWT is stale-auth (credential death) — and
5541
- * that is knowable LOCALLY, without the network, so it is decided FIRST, before the error type. On
5542
- * the wire the broker's rejection and the socket close race: a slow CI/Windows handshake can
5543
- * surface a bare transport failure (→ "unreachable") instead of a clean AuthorizationError, which
5544
- * used to misclassify a dead cred. Reading the cred removes that timing dependency entirely, so the
5545
- * classification is deterministic. Unreadable content falls through to the wire truth (no false
5546
- * stale diagnosis from garbage). `e` is undefined when the gate refused before any connect.
5547
- * `authRequired` is true when the gate read a greeting that asked for auth. `otherwise` is the
5548
- * verdict when nothing more specific applies. */
5549
- function classifyProbeFailure(e, opts, authRequired = false, otherwise = "unreachable") {
5550
- if (typeof opts.creds === "string") {
5551
- try {
5552
- if (inspectCredHealth(opts.creds).state === "expired")
5553
- return { ok: false, reason: "stale-auth" };
5554
- }
5555
- catch { /* not introspectable — keep the wire truth */ }
5556
- }
5557
- if (e instanceof UserAuthenticationExpiredError)
5558
- return { ok: false, reason: "stale-auth" };
5559
- // The broker answered but rejected these creds (so it IS up) — auth-required, not stale-auth.
5560
- if (e instanceof AuthorizationError)
5561
- return { ok: false, reason: "auth-required" };
5562
- // A dial that ran out of its own budget is neither a refusal nor a dead broker — it is latency,
5563
- // and grading it `unreachable` made a TLS-required target read as a trust failure (#851). Only
5564
- // nats-core's TimeoutError means that: a peer's `-ERR` that mentions a timeout answered at once.
5565
- if (e instanceof TimeoutError)
5566
- return { ok: false, reason: "timeout" };
5567
- // The native client read a greeting without TLS support and refused the TLS requirement.
5568
- // That is a transport mismatch, not an unreachable listener or proof of mesh identity.
5569
- if (e instanceof ConnectionError && e.message === "server does not support 'tls'")
5570
- return { ok: false, reason: "tls-unsupported" };
5571
- // A broker that greeted us asking for auth and then reset the handshake most likely refused it.
5572
- // Windows can discard its `-ERR 'Authorization Violation'` when the reset lands, so the client
5573
- // sees only ECONNRESET, and a running auth broker used to read as gone. No rejection was read, so
5574
- // the verdict is marked inferred.
5575
- if (authRequired && e?.code === "ECONNRESET")
5576
- return { ok: false, reason: "auth-required", inferred: true };
5577
- return { ok: false, reason: otherwise };
5578
- }
5579
4497
  //# sourceMappingURL=endpoint.js.map