@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.
@@ -1,7 +1,7 @@
1
1
  export { MULTI_FILTER_BATCH, MULTI_FILTER_READ_CONCURRENCY } from "./endpoint-history.js";
2
2
  import { type NativeConnectionBinding } from "./native-connection.js";
3
3
  import { EventEmitter } from "node:events";
4
- import { connect, type NatsConnection } from "@nats-io/transport-node";
4
+ import { type NatsConnection } from "@nats-io/transport-node";
5
5
  import { type LivenessAnswer, type LivenessPlane, type ResponderState } from "./liveness.js";
6
6
  import { type PresenceView } from "./endpoint-presence.js";
7
7
  export { PresenceWriteStuckError, type PresenceView } from "./endpoint-presence.js";
@@ -13,267 +13,16 @@ import type { EndpointReply } from "./endpoint-envelope.js";
13
13
  import type { CompiledContract } from "./schema-profile.js";
14
14
  import type { RegistryEndpointsInput, RegistryEndpointsOutput } from "./registry-contract.js";
15
15
  import type { EpVerbTarget, EpAttributedReply } from "./endpoint-verbs.js";
16
- import type { AgentCard, ChannelConfig, ControlReply, ControlRequest, ControlRequestInit, Delivery, EndpointRef, MessageMeta, Part, Presence, PresencePrompts, PresenceStatus, PresenceCondition, AttentionMode, ChannelMode, CotalMessage, DmHistoryRead, HistoryMessage, DeliveryClass, MembershipChange, MembershipSnapshot } from "./types.js";
16
+ import type { AgentCard, ChannelConfig, ControlReply, ControlRequest, ControlRequestInit, EndpointRef, Part, Presence, PresencePrompts, PresenceStatus, PresenceCondition, AttentionMode, ChannelMode, CotalMessage, DmHistoryRead, HistoryMessage, DeliveryClass, MembershipChange, MembershipSnapshot } from "./types.js";
17
17
  import type { DeliveryLeaseInfo, ManagerLeaseInfo } from "./lease.js";
18
18
  import { type MaybePromise } from "./endpoint-delivery-plane.js";
19
19
  import { type AnycastStatus } from "./anycast-requests.js";
20
- import { type ParsedSubject } from "./subjects.js";
21
20
  import { isPermissionDenied } from "./permission-denied.js";
22
21
  export { isPermissionDenied };
23
- export declare const DEFAULT_SERVER = "nats://127.0.0.1:4222";
24
- /** The DLV count a stored copy was written under, from its {@link DELIVERY_LIMIT_HEADER} (SPEC §8):
25
- * a whole number of at least 1, null for `none`, and 1000 when the header is absent, since only a
26
- * daemon from before the count was configurable writes a copy without it and its count was 1000.
27
- * Throws on any other value. */
28
- export declare function deliveryLimitOf(value: string | undefined): number | null;
29
- /** Space joined when none is given on the CLI (the `cotal-<space>` cmux tab, etc.). */
30
- export declare const DEFAULT_SPACE = "main";
31
- export interface EndpointOptions {
32
- /** Trusted composition custody of each opened transport, including replacement epochs.
33
- * Called before binding so the owner can await its terminal closed signal on bind failure. */
34
- onConnection?: (nc: NatsConnection) => void;
35
- /** A planned credential swap dials a second connection, calls {@link onConnection}, and flushes
36
- * before it reconnects the resident connection. The second connection closes after that
37
- * reconnect. `onConnection` must accept a connection that exists only for the swap. Serve
38
- * subscriptions that share an incarnation queue keep dispatch while the resident connection
39
- * is down. Without this option the resident connection reconnects in place. */
40
- overlapOnConnectionRenewal?: boolean;
41
- /** Await local admission checks before presence, consumers and the ready event on each bind. */
42
- beforeBind?: () => Promise<void>;
43
- /** The collaboration to join. */
44
- space: string;
45
- /** Identity. `id` is generated if omitted. */
46
- card: Omit<AgentCard, "id"> & {
47
- id?: string;
48
- };
49
- /** Opaque presence label. Omitted reads COTAL_ENVIRONMENT; null omits the label without reading it. */
50
- environment?: string | null;
51
- /** This incarnation's lifecycle UID (SPEC §13.1), minted ONCE per lifecycle by the provisioning
52
- * authority (manager/CLI: `mintLifecycleUid()`) and PERSISTED with the agent — never re-minted per
53
- * process, or a supervised restart would abandon the durable inbox. REQUIRED to bind/create the
54
- * lifecycle-keyed messaging durables (`dm_…-<uid>`, `dlv_…-<uid>`, `chathist_…-<uid>`) — an
55
- * endpoint without one (a pure operator/daemon connection) can not consume DM/chat history. */
56
- lifecycleUid?: string;
57
- /** The CHAT stream sequence this incarnation had reached before its preservation cut (a supervised
58
- * preserve/resume, never a fresh join). The boot backfill reads only what came after it instead of
59
- * the whole retained window. Core reads no environment variable for this — the caller (a launcher)
60
- * resolves it and passes it explicitly. */
61
- backfillFloor?: number;
62
- /** The accepted-row token of this credential's issuance (SPEC 13.15). Set when the launcher
63
- * minted the credential as an issuance: after connecting, the endpoint reads the generation the
64
- * ISSUER bound under this token (a broker-enforced per-key read) and pins it into every caller
65
- * rail it forms. A token that resolves to no row, or to another incarnation's reference, fails
66
- * the connect: the rails would be refused at the broker anyway, and a silent legacy fallback is
67
- * exactly what the versioned rail exists to rule out. */
68
- acceptedToken?: string;
69
- servers?: string;
70
- /** Connection token (soft-shared auth). Mutually exclusive with user/pass. */
71
- token?: string;
72
- /** Username/password auth (both required together). */
73
- user?: string;
74
- pass?: string;
75
- /** NATS user creds file *content* (JWT + nkey seed), or a SOURCE that mints/reads a fresh copy.
76
- * When set, the endpoint authenticates as that user and adopts the creds' identity as its card.id.
77
- *
78
- * A STRING is the ordinary static cred. A FUNCTION is the STANDING-RENEWAL seam for
79
- * bounded-lifetime standing creds: the endpoint fetches before the first connect, re-fetches at
80
- * 75% of each JWT's lifetime (then swaps the connection onto the fresh cred with a controlled
81
- * reconnect) and on rebuilds, and every (re)connect attempt presents the freshest copy — the
82
- * broker's expiry-close is only the backstop for a missed swap.
83
- * The two source shapes are the renewal classes: a seed-holder self-remints (the manager's
84
- * supervisor), a seed-less daemon re-reads its manager-reminted creds file (delivery). A source
85
- * requires explicit `card.id` (the pinned identity); every fetched cred MUST carry that same nkey
86
- * or the endpoint fails loud — renewal may never silently swap identity. A fetch failure is
87
- * emitted as a "warning" event and retried; the connection stays up until its current JWT expires,
88
- * so a dead reminter is loud without instantly dropping the mesh. Node rethrows unhandled "error"
89
- * events, so a retry notice must not use that channel (#891). Once the cached cred expires,
90
- * the endpoint refuses to present it to the broker and keeps retrying the source with backoff. */
91
- creds?: string | (() => Promise<string>);
92
- /** USER-MODE auth: a validated Cotal user bearer (the JWT from `cotal login` → the IdP bridge), or a
93
- * SOURCE that mints a fresh one. When set, the endpoint connects through the auth callout — presenting
94
- * {@link sentinelCreds} + the bearer, the broker mints its scoped data-account JWT.
95
- *
96
- * A STRING is a one-shot bearer for connection-lifetime ≤ bearer-lifetime callers (the CLI): the
97
- * owner+actor PRINCIPAL is derived from it (`sub`, `act.actor`), and the connection dies at the
98
- * bearer-bound JWT expiry. A FUNCTION is a bearer source for long-lived endpoints (spawned agents):
99
- * the endpoint fetches before the first connect, renews at a random point between 50% and 80% of
100
- * each token's lifetime (then swaps the connection onto it with a controlled reconnect) and on
101
- * rebuilds, and every (re)connect attempt presents the freshest unexpired token — so reconnects
102
- * outlive any single bearer, and none presents an expired one.
103
- * A source requires explicit `card.owner` + `card.actor` (there is no bearer to derive them from at
104
- * construction); every fetched bearer MUST carry that same principal or the endpoint fails loud.
105
- * A fetch failure is emitted as one "warning" event per run of failures and retried on a jittered,
106
- * capped backoff — the connection stays up until its current JWT expires, so a dead auth service
107
- * surfaces loudly without instantly dropping the mesh. A failure that carries a numeric
108
- * `retryAfterSeconds` is retried when those seconds have passed instead, not before.
109
- * Node rethrows unhandled "error" events, so a retry notice must not use that channel (#891).
110
- * Mutually exclusive with `creds`/`token`/`user`/`pass`; requires `sentinelCreds`. */
111
- bearer?: string | (() => Promise<string>);
112
- /** The shared, deny-all auth-account sentinel creds presented alongside {@link bearer} so the connect
113
- * lands in the callout account (`createCalloutAuth().sentinelCreds`). Powerless on its own. */
114
- sentinelCreds?: string;
115
- /** Require a TLS connection to the server. */
116
- tls?: boolean;
117
- /** Native NATS PING interval for this endpoint's resident connection, in milliseconds.
118
- * Defaults to 10 seconds. Pair with transportMaxPingOut. No probe connection. */
119
- transportPingIntervalMs?: number;
120
- /** Unanswered native PING count before the resident transport becomes stale. Defaults to 2.
121
- * Pair with transportPingIntervalMs for bounded silent loss. */
122
- transportMaxPingOut?: number;
123
- /** How long the first connect may take before it fails with the transport's TimeoutError, in
124
- * milliseconds. Omitted uses the transport's default. */
125
- transportConnectTimeoutMs?: number;
126
- /** Channels to subscribe to; the first concrete one is the default broadcast target. Omitted or
127
- * empty ⇒ NO channels: the endpoint joins nothing, and {@link CotalEndpoint.multicast} refuses
128
- * a call with no explicit channel rather than picking one. */
129
- channels?: string[];
130
- /** The credential's complete channel read ACL when the composition has it. An explicit empty list
131
- * means provisioning omitted the DLV durable. When omitted, static credentials select the optional
132
- * bind from their presented publish permissions; bearer callers need the resolved ACL. A denied
133
- * bind still refuses startup. */
134
- allowSubscribe?: string[];
135
- /** Presence heartbeat interval (ms). */
136
- heartbeatMs?: number;
137
- /** Presence liveness window (ms); a peer is considered gone after this. */
138
- ttlMs?: number;
139
- /** Publish our own presence (default true). */
140
- registerPresence?: boolean;
141
- /** Track the roster of peers with a live watch (default true). Every watcher receives every
142
- * member's heartbeat, so a space of K watching members moves K² deliveries per heartbeat. An
143
- * endpoint that only needs the roster when it acts sets this false and calls
144
- * {@link CotalEndpoint.readPresence} instead (SPEC §6). */
145
- watchPresence?: boolean;
146
- /** Keep the channel registry cache (default true). An endpoint that watches presence watches the
147
- * registry; a consumer that reads presence on demand reads the registry on demand too
148
- * ({@link CotalEndpoint.readChannels}), and any other endpoint keeps no cache. A presence-only
149
- * supervisor sets this false to track the roster WITHOUT opening the channel-registry cache — so
150
- * its cred needs no channel-registry read grant (residual 2). A consumer always opens the
151
- * registry, because the join-time replay decision reads it. */
152
- watchChannels?: boolean;
153
- /** Read presence and the channel registry ONCE at start instead of watching them (default false),
154
- * for an endpoint that does one thing and stops (`cotal send`, a roster probe). Each read is a
155
- * batched Direct Get of every key's last record, so it binds no consumer. A watch's ordered consumer
156
- * outlives {@link CotalEndpoint.stop} by the broker's five-minute inactive threshold, because the
157
- * operator and agent profiles hold no CONSUMER.DELETE on these buckets (#691), and one per
158
- * short-lived process piles up until the broker refuses new consumers there (#4091). The roster
159
- * and the channel cache hold the state at start and never update, and no sweep runs. Requires
160
- * `consume` and `registerPresence` false. */
161
- readOnce?: boolean;
162
- /** Consume ONLY this endpoint's own existing DM durable, for a credential that can read nothing
163
- * else. The endpoint binds `dm_<owner>-<actor>-<uid>` and opens no channel registry, presence,
164
- * KV, channel subscription, `dlv_` durable, history reader or JetStream manager. It never creates
165
- * the durable: a missing one fails start with {@link DmDurableMissingError}, a refused bind with
166
- * {@link DmBindRefusedError}. Each authenticated DM goes to `handler`, one at a time; the next is
167
- * not read until the previous handler settles. The `message` event does not fire in this mode.
168
- * {@link CotalEndpoint.stop} resolves only after the connection is closed and the running handler
169
- * has settled; a rejecting handler still lets the connection close, and stop throws, keeping
170
- * custody, when closure or settlement within `settleTimeoutMs` (default 30000) is unproved.
171
- * A copy received after stop begins or after a reconnect replaces the connection is never
172
- * handed to the handler and stays unacked for broker redelivery; an ack, nak or in-progress
173
- * signal on a closed connection throws.
174
- * Requires static or sourced creds or a bearer, `consume` true, `registerPresence`,
175
- * `watchPresence` and `watchChannels` false, and no channels, role, `readOnce` or `acceptedToken`. */
176
- dmOnly?: DmOnlyOptions;
177
- /** Create inbound stream consumers (DM / chat / anycast). Default true; a pure observer sets false. */
178
- consume?: boolean;
179
- /** Initial per-channel attention overrides to publish in presence from the first heartbeat (the
180
- * connector's file-default seed). Mirror only — never read back into delivery. */
181
- channelModes?: Record<string, ChannelMode>;
182
- /** How long an unacked (un-surfaced) message waits before redelivery (ms). */
183
- ackWaitMs?: number;
184
- /** Retire this instance's durable consumers after it's been gone this long (ms). */
185
- inactiveThresholdMs?: number;
186
- }
187
- /** A peer subscribed to a channel — broker truth (a chat-stream consumer) joined with
188
- * presence for liveness. `live: false` is a stale ghost: the durable lingers (reconnect
189
- * grace) but presence says the peer is gone/offline. */
190
- export interface ChannelMember {
191
- id: string;
192
- name: string;
193
- role?: string;
194
- live: boolean;
195
- }
196
- /** See {@link EndpointOptions.dmOnly}. */
197
- export interface DmOnlyOptions {
198
- /** Receives each authenticated DM. A resolved promise does not ack: call `delivery.ack()`. A
199
- * rejection is emitted as `error` and leaves the copy unacked, so the broker redelivers it. */
200
- handler: (msg: CotalMessage, delivery: Delivery, meta: MessageMeta) => void | Promise<void>;
201
- /** How long {@link CotalEndpoint.stop} waits for a running handler, in milliseconds. */
202
- settleTimeoutMs?: number;
203
- }
204
- /** This endpoint's own `dm_` durable does not exist. A DM-only endpoint, and any endpoint on an
205
- * authenticated mesh, binds the durable its provisioner created and never creates one. */
206
- export declare class DmDurableMissingError extends Error {
207
- readonly stream: string;
208
- readonly durable: string;
209
- readonly code: "dm-durable-missing";
210
- constructor(stream: string, durable: string);
211
- }
212
- /** The broker refused a DM-only endpoint's bind of its own `dm_` durable. No other credential or
213
- * read path is tried. */
214
- export declare class DmBindRefusedError extends Error {
215
- readonly stream: string;
216
- readonly durable: string;
217
- readonly code: "dm-bind-refused";
218
- constructor(stream: string, durable: string, cause: unknown);
219
- }
220
- /** Raw NATS transport liveness for the endpoint's CURRENT connection epoch. This is deliberately
221
- * separate from the `connection` event, which means the full Cotal bind is ready. */
222
- export interface TransportState {
223
- connected: boolean;
224
- /** The server nats.js named for this edge. Omitted when the runtime supplied none. */
225
- server?: string;
226
- }
227
- /**
228
- * Events: "message" (CotalMessage), "presence" (PresenceEvent), "roster" (Presence[]), "error" (Error),
229
- * "connection" ({ connected: boolean }) — true on every successful (re)bind (initial start, manual
230
- * reconnect, AND background self-heal), false the moment the connection drops (rebuild null window /
231
- * terminal close). Lets an in-process agent track connectedness off the endpoint's own (re)binds
232
- * instead of an imperative flag the self-heal path can't reach; "transport" ({ connected, server? })
233
- * is the lower-level NATS socket edge, true before the full bind finishes and false during an internal
234
- * nats.js reconnect without changing `connection` readiness. "stored-copies-full" ({ limit: number }): a
235
- * stored copy arrived with the store at the count the copy was written under ({@link deliveryLimitOf}),
236
- * so the store may have discarded older copies before this session read them; emitted for each such
237
- * copy. A lowering of the count or an age set on the store removes copies without this event.
238
- *
239
- * Callers MUST attach an "error" listener before `start()`: async faults (incl. NATS
240
- * permission denials, surfaced via `watchStatus`) are emitted as "error", and Node throws
241
- * synchronously on an unhandled "error" — a missing listener turns any such fault into a
242
- * process crash instead of a logged denial.
243
- */
244
- /** One page of a mediated history read: the newest `limit` messages, oldest-first WITHIN the page.
245
- *
246
- * `complete` is the honest-truncation signal and the reason this is not just `CotalMessage[]`:
247
- * `true` means the page reaches the start of the channel's RETAINED history (nothing older is on
248
- * the stream to read), `false` means older messages exist behind it. A caller that cannot tell
249
- * those apart renders "there is more" as "this is the beginning of the conversation". It says
250
- * nothing about messages already aged out by retention — no reader can see those. */
251
- export type HistoryPage = {
252
- items: CotalMessage[];
253
- complete: boolean;
254
- };
255
- /** The NEWEST prefix-from-the-end of `items` whose serialized `readHistory` reply fits `budget`
256
- * bytes, order preserved. Returns `[]` when not even the newest single message fits — the caller
257
- * must refuse loudly there rather than serve an empty page, which would read as "no history".
258
- *
259
- * The `ControlReply` around the items rides the same NATS message, so it is charged too: items
260
- * that fit on their own can still make a reply the broker refuses.
261
- *
262
- * Measured in ENCODED bytes, not `string.length`: a page of multi-byte text would otherwise be
263
- * undercounted and still overflow the broker. Same discipline as `assertFactFits`. */
264
- export declare function fitHistoryPage(items: CotalMessage[], budget: number): CotalMessage[];
265
- /** A served principal endpoint (SPEC 13.21). */
266
- export interface PrincipalServe {
267
- /** Resolves once the broker accepted this process's subscription; rejects with its refusal. */
268
- readonly ready: Promise<void>;
269
- /** Resolves with the refusal that ended the serve, including one that arrives on a replaced
270
- * connection after `ready` resolved. Never rejects, and never resolves after `stop`. */
271
- readonly failed: Promise<Error>;
272
- /** Unsubscribe, abort every handler's `signal`, and wait for each handler in flight until its
273
- * request's deadline at most, which the route caps at 30 s. A reply that comes after that is
274
- * dropped. */
275
- stop(): Promise<void>;
276
- }
22
+ export { DEFAULT_SERVER, isPublishPermissionDenied, wsServers, defaultProbeTimeoutMs, dialerFor, isAuthRejection, isReachable, type ProbeResult, probeConnect, } from "./endpoint-dial.js";
23
+ import { type EndpointOptions, type ChannelMember, type HistoryPage, type PrincipalServe } from "./endpoint-options.js";
24
+ export { deliveryLimitOf, DEFAULT_SPACE, type EndpointOptions, type ChannelMember, type DmOnlyOptions, DmDurableMissingError, DmBindRefusedError, type TransportState, type HistoryPage, fitHistoryPage, type PrincipalServe, } from "./endpoint-options.js";
25
+ export { isFromSubjectSender, } from "./endpoint-messages.js";
277
26
  export declare class CotalEndpoint extends EventEmitter {
278
27
  readonly card: AgentCard;
279
28
  readonly space: string;
@@ -550,172 +299,43 @@ export declare class CotalEndpoint extends EventEmitter {
550
299
  private get authed();
551
300
  start(): Promise<void>;
552
301
  private startOnce;
553
- /** The floor on a bearer renewal's delay. A token whose whole lifetime sits under it is renewed at
554
- * this cadence (`expiry-renewal` mints 5s bearers). */
555
- private static readonly BEARER_MIN_RENEWAL_MS;
556
- /** A failed bearer renewal retries after about this long, doubling per failure up to the cap. */
557
- private static readonly BEARER_RETRY_MS;
558
- private static readonly BEARER_RETRY_CAP_MS;
559
302
  /**
560
303
  * A condition the endpoint is already surviving. Node rethrows `error` when no listener is
561
304
  * attached, so emitting retry notices on `error` killed hosts that the endpoint intended to
562
305
  * keep running (#891). `warning` is observable and never fatal without a listener.
563
306
  */
564
307
  private emitRecoverable;
565
- /** Fetch a fresh bearer from the source, pin its principal to ours, arm the next renewal. On a
566
- * fetch/principal failure: THROWS when `initial` (start() must fail loud before first connect);
567
- * otherwise retries on a jittered, capped backoff, and warns once for the whole run of failures —
568
- * the live connection keeps working until its current JWT expiry, so a dead auth service is
569
- * loud without instantly dropping the mesh, and without a line per attempt. */
308
+ /** The resident swap a reload scheduled, until its connection is back or the gate's bound ends. */
309
+ private residentSwap?;
310
+ /** Serializes every prove-then-adopt transaction (the 75% timer and the explicit reload) so a timer
311
+ * tick and an explicit reload can never interleave their fetch/preflight/commit — the design's
312
+ * single-flight requirement. Runs `fn` after any in-flight transaction settles, whatever its
313
+ * outcome; the internal chain never rejects. */
314
+ private credsTxn;
315
+ /** The bearer and credential renewal of this endpoint. Every dependency is read when it is used, so
316
+ * a field assigned after construction is seen. */
317
+ private readonly credentials;
318
+ /** Forwards to the credentials component's {@link EndpointCredentials.refreshBearer}. */
570
319
  private refreshBearer;
571
- private armBearerTimer;
572
- /** The timed renewal. A new token moves the live connection onto itself at once, through the
573
- * same controlled reconnect the creds path uses, so the broker never has to expire a connection
574
- * this endpoint could renew. With no live connection, it ends the rebuild loop's wait instead:
575
- * that loop refuses to dial an expired token and leaves the retries to this timer. */
576
- private renewBearerOnTimer;
577
- /** The cached bearer, checked: every (re)connect attempt reads it, the reconnects nats.js runs
578
- * on its own included, so none presents an expired token, which the callout could only deny
579
- * after a full round trip. The bearer counterpart of {@link credsForWire}. */
320
+ /** Forwards to the credentials component's {@link EndpointCredentials.bearerForWire}. */
580
321
  private bearerForWire;
581
- /** How soon a FAILED creds refresh retries. Successful refreshes schedule by lifetime fraction
582
- * (75% of iat→exp), not a fixed margin — standing creds span hours to days, bearers minutes. */
583
- private static readonly CREDS_RETRY_MS;
584
- /** THE ONE PLACE a credential is cleared for presentation to a broker.
585
- *
586
- * The property is unconditional — this endpoint never presents a credential it has already
587
- * decoded as expired — so it is a property of the SUPPLY, not of any one dial site. It used to
588
- * live inside {@link bindConnection}, which only `start()` and `doRebuild` reach; the
589
- * authenticator nats.js re-evaluates on ITS OWN reconnects read the cache directly and so
590
- * presented whatever was last fetched, expired included. Two such reconnects exist and neither
591
- * passes through bindConnection: the one the broker forces at JWT `exp`, and an ALREADY RUNNING
592
- * dial loop from an earlier drop that crosses `exp` while it retries (the pre-expiry
593
- * reconnect fence flips a policy flag nats-core only reads when it observes a NEW drop, so it
594
- * cannot stop a loop already in flight).
595
- *
596
- * Putting the refusal here instead means a future caller cannot miss it: the only way to reach a
597
- * dial is through {@link credsForWire}, and the one presentation that does not read the cache
598
- * (the adoption preflight, which presents a fresh CANDIDATE) calls this same function on it.
599
- *
600
- * An unbounded credential (no numeric `exp`) is presentable: bounded lifetimes are the renewal
601
- * seam's concern, and a cred with no expiry has none to be past. */
602
- private static presentableCreds;
603
- /** The connect attempt's credential getters: what {@link credsForWire} and {@link bearerForWire}
604
- * return, with its expiry recorded as {@link presentedExp}. */
322
+ /** Forwards to the credentials component's {@link EndpointCredentials.presentCreds}. */
605
323
  private presentCreds;
324
+ /** Forwards to the credentials component's {@link EndpointCredentials.presentBearer}. */
606
325
  private presentBearer;
607
- /** The cached credential, checked. Handed to nats.js as the authenticator's source on EVERY auth
608
- * mode (renewed or static), so each (re)connect attempt — ours or the library's — re-reads a
609
- * CHECKED value. A refusal throws out of the authenticator, which nats-core turns into a closed
610
- * connection rather than a CONNECT carrying dead material; the endpoint's own supervisor then
611
- * rebuilds on capped backoff, and {@link bindConnection} re-fetches from the source on each of
612
- * those attempts, so a renewal that starts working recovers the endpoint without presenting
613
- * anything expired in the meantime. Deliberately side-effect free: kicking the renewal timer
614
- * from here would retry the source once per dial attempt, which is the flat load on a dead
615
- * broker that {@link RETRY_BACKOFF_CAP_MS} exists to prevent. */
616
- private credsForWire;
617
326
  /** The credential this endpoint presents on its next connect, checked as {@link credsForWire}
618
327
  * checks it. A second connection under the same identity reads it on every attempt, so it
619
328
  * presents each credential this endpoint adopts and never an expired one. */
620
329
  wireCreds(): string;
621
- /** Refuses a fetched generation there is nothing to renew FROM, so the caller's failure posture
622
- * ({@link CREDS_RETRY_MS}) applies instead of the renewal schedule (issue #1523).
623
- *
624
- * A source that hands back the SAME generation past its own renewal point has not re-signed yet:
625
- * that is a missed remint, not a candidate. Adopting it re-arms from a non-positive delay, which
626
- * {@link armCredsRefresh} floors to 1s, which fetches again, which is the same generation — a 1s
627
- * read loop against a store that is already having a bad day, for the JWT's remaining 25% of life,
628
- * with the 60s backoff that exists for exactly this bypassed because the fetch did not FAIL.
629
- *
630
- * The membership feed's rw-cred renewal already refuses it this way (`membership-feed.ts`,
631
- * `adoptRwCreds`: "the rw source still holds the previous generation past its renewal point");
632
- * this is the same rule on the endpoint's `delivery.creds` seam, so the two renewal paths answer
633
- * a dead source identically.
634
- *
635
- * An ALREADY-EXPIRED generation is refused whatever it is: the delay is non-positive for it too,
636
- * but it is dead rather than merely due, so it is named separately and refused even when the
637
- * source keeps returning a different one. */
638
- private static assertRenewableGeneration;
639
- /** The disposable-preflight connect bound for the EXPLICIT reload proof (D5 class-2 adoption). A
640
- * rogue or unreachable candidate must resolve well UNDER the manager's delivery-admin request
641
- * bound, so this stays a few seconds and never blocks the responder. */
642
- private static readonly PREFLIGHT_MS;
643
- /** How long the resident wire swap is deferred past the reply on the EXPLICIT reload path. The
644
- * delivery-admin responder rides THIS connection, so `nc.reconnect()` must not run until the
645
- * reply has flushed on the still-live old cred; the old cred stays valid until its exp, so a short
646
- * deferral is safe. */
647
- private static readonly RESIDENT_SWAP_DEFER_MS;
648
- /** How long a delivery-admin request read after a reload waits for the resident swap's reconnect.
649
- * nats.js drops a publish made while the connection is down when it redials, so a reply sent
650
- * during the swap is lost and its caller waits out its whole request timeout. Past this bound the
651
- * request is answered anyway, as it was before the gate. */
652
- private static readonly RESIDENT_SWAP_GATE_MS;
653
- /** The resident swap a reload scheduled, until its connection is back or the gate's bound ends. */
654
- private residentSwap?;
655
- /** The daemon-side deadline for the WHOLE prove-then-adopt transaction (source fetch + preflight +
656
- * commit), kept strictly BELOW the manager's delivery-admin request bound so a slow or hung hosted
657
- * store returns a structured component failure rather than an ambiguous client timeout, and a late
658
- * fetch can never commit after the caller gave up. */
659
- private static readonly RELOAD_DEADLINE_MS;
660
- /** Fetch fresh creds from the source, pin their identity to ours, cache them, and arm the next
661
- * refresh at 75% of the new JWT's lifetime. THROWS on fetch/pin failure — the callers decide the
662
- * failure posture (loud-and-retry for the timer, a structured error reply for an explicit
663
- * {@link reloadCreds}). This is the PASSIVE-BACKSTOP fetch; the explicit auditable path
664
- * ({@link reloadCreds}) does its own fetch so it can preflight the candidate on a disposable
665
- * connection BEFORE mutating this live cache. */
666
- private fetchFreshCreds;
667
- /** Swap the live connection onto the freshest cached cred or bearer with a controlled
668
- * `nc.reconnect()` (nats.js re-evaluates the authenticator per attempt). Swapping now, instead of
669
- * waiting for the broker to close the connection at `exp`, means the wire never carries a
670
- * near-dead JWT and the operator never sees a spurious "authentication expired". After the
671
- * reconnect succeeds, re-arm the expiry fence for the credential now authenticated on the wire. */
672
- private swapConnectionOntoFreshCreds;
673
- /** A second connection whose `onConnection` subscriptions are flushed before the resident
674
- * reconnect. Its inbox is not the resident connection's inbox. A flush that does not finish
675
- * closes it and leaves the caller to reconnect in place. */
676
- private openRenewalOverlap;
677
- /** nats-core keeps its reconnect switch on the protocol handler. This pinned internal shape is the
678
- * same last-resort surface used by {@link closeFailedBind}; there is no public API for changing the
679
- * reconnect policy of an existing connection. Disabling it does not disable Cotal self-heal: the
680
- * `nc.closed()` supervisor below rebuilds the endpoint with freshly checked auth material. */
330
+ /** Forwards to the credentials component's {@link EndpointCredentials.disableLibraryReconnect}. */
681
331
  private disableLibraryReconnect;
682
- /** Close a connection whose library reconnect has already been disabled. `drain()` flushes with a
683
- * PING and waits for the matching PONG; nats-core only rejects that waiter inside reconnect
684
- * `prepare()`, so a half-open socket with reconnect=false leaves drain pending until the 2-minute
685
- * ping interval times out. `close()` tears the transport down without that round-trip, which is
686
- * the same public path {@link closeFailedBind} already uses when there is no graceful delivery
687
- * contract left. */
332
+ /** Forwards to the credentials component's {@link EndpointCredentials.closeWithoutLibraryReconnect}. */
688
333
  private closeWithoutLibraryReconnect;
689
- /** Disable nats-core reconnect shortly before the JWT authenticated on this wire expires. The small
690
- * lead makes the policy change precede the broker's expiry close even when both timers wake in the
691
- * same event-loop turn. A credential adoption does not move this fence until the resident reconnect
692
- * is requested, so the old wire remains protected during the prove-then-adopt window. */
334
+ /** Forwards to the credentials component's {@link EndpointCredentials.armAuthExpiryReconnectFence}. */
693
335
  private armAuthExpiryReconnectFence;
694
- /** The connectAndBind PRE-CONNECT fetch: pull the freshest source cred and pin it into
695
- * {@link currentCreds} so the connect() that immediately follows presents it — that connect IS the
696
- * proof, so NO preflight and NO live swap here. THROWS when `initial` (no cred to start from), else
697
- * emits and retries. The LIVE-SWAP paths — the 75% timer {@link renewCredsOnTimer} and the explicit
698
- * {@link reloadCreds} — preflight the candidate on a disposable connection instead, so they never
699
- * reconnect the live connection onto an unproven cred. */
336
+ /** Forwards to the credentials component's {@link EndpointCredentials.refreshCreds}. */
700
337
  private refreshCreds;
701
- /** Serializes every prove-then-adopt transaction (the 75% timer and the explicit reload) so a timer
702
- * tick and an explicit reload can never interleave their fetch/preflight/commit — the design's
703
- * single-flight requirement. Runs `fn` after any in-flight transaction settles, whatever its
704
- * outcome; the internal chain never rejects. */
705
- private credsTxn;
706
- private runCredsTxn;
707
- /** The one PROVE-then-adopt transaction shared by the 75% timer and the explicit reload (run under
708
- * {@link runCredsTxn}). Fetch (deadline-bounded) → identity-pin → optional `expected` fingerprint →
709
- * PREFLIGHT the candidate on a disposable connection → fence a late commit against the deadline →
710
- * commit {@link currentCreds} → arm the next 75% timer. Because currentCreds is written ONLY after
711
- * the preflight proves broker acceptance, the resident authenticator getter can never present an
712
- * unproven cred (not even on an incidental reconnect), and a rejected candidate leaves the resident
713
- * connection untouched on BOTH the timer and explicit paths. THROWS (structured) on any failure. */
714
- private adoptFreshCreds;
715
- /** The 75%-of-lifetime renewal timer tick: prove + adopt + swap the LIVE connection. Preflights (it
716
- * reconnects a live connection, so the candidate must be broker-proven first) and is serialized
717
- * with the explicit reload. Never throws — a failed renewal logs and retries while the old cred
718
- * stays live until its expiry. */
338
+ /** Forwards to the credentials component's {@link EndpointCredentials.renewCredsOnTimer}. */
719
339
  private renewCredsOnTimer;
720
340
  /** Fetch, broker-prove and adopt the source credential, then refresh the same connection
721
341
  * once outgoing mux and named-reply requests are quiet. A busy timeout retains the connection
@@ -743,18 +363,8 @@ export declare class CotalEndpoint extends EventEmitter {
743
363
  iat?: number;
744
364
  exp?: number;
745
365
  }>;
746
- /** Arm the resident wire swap for the delivery-admin `reloadCreds` path. Called by
747
- * {@link handleDeliveryAdmin} ONLY after BOTH component proofs have settled and immediately before
748
- * the reply is returned+responded — never from inside {@link reloadCreds} while the aggregate is
749
- * still open, or a slow co-component proof would let `nc.reconnect()` reconnect the admin rail
750
- * before the reply flushes and silently strand it. The short deferral lets the reply flush on the
751
- * still-live old cred first. Best-effort — the proof was the preflight; a transient swap failure is
752
- * retried by the 75% timer and the broker's own expiry-close, both presenting the adopted candidate.
753
- * Until the swapped connection is back, {@link residentSwap} holds the delivery-admin requests that
754
- * arrive after this reply. */
366
+ /** Forwards to the credentials component's {@link EndpointCredentials.scheduleResidentSwap}. */
755
367
  private scheduleResidentSwap;
756
- /** Resolve when this endpoint reports its transport connected again, or after `ms`. */
757
- private transportBack;
758
368
  private armCredsRefresh;
759
369
  /** Open the connection and bind everything that hangs off it: status watch, presence
760
370
  * watch + heartbeat, channel registry, and the durable consumers. Re-runnable — a
@@ -2412,124 +2022,4 @@ export declare class CotalEndpoint extends EventEmitter {
2412
2022
  private readChannelsOnce;
2413
2023
  private sweep;
2414
2024
  }
2415
- /** SPEC §5 on receive: a delivery comes from the principal its subject names. The payload is an
2416
- * object whose `from.id` is the subject's sender, and the subject's owner is a real principal, not
2417
- * an old-shape alias. Every receive path asks this one predicate. What a path does with a refusal
2418
- * (drop, skip, ack, term or reject) and its own extra checks (a usable id, its own echo) stay with
2419
- * the path. */
2420
- export declare function isFromSubjectSender(msg: unknown, parsed: ParsedSubject): boolean;
2421
- /** Auth subset of connect() options, shared by the endpoint and isReachable. `bearer` may be a
2422
- * sync GETTER — nats.js re-evaluates token authenticators per (re)connect attempt, which is how a
2423
- * refreshing endpoint presents its freshest bearer without rebuilding the connection options. */
2424
- interface AuthOpts {
2425
- token?: string;
2426
- user?: string;
2427
- pass?: string;
2428
- /** May be a sync GETTER (like `bearer`) — the authenticator then re-reads it per (re)connect
2429
- * attempt, which is how a standing-renewal endpoint presents its freshest cred. */
2430
- creds?: string | (() => string);
2431
- /** Observe only the credential actually presented, including native reconnect authentication. */
2432
- onCreds?: (creds: string) => void;
2433
- bearer?: string | (() => string);
2434
- sentinelCreds?: string;
2435
- tls?: boolean;
2436
- }
2437
- /** True ONLY for a denial on a **publish** — the single case that proves the message was never
2438
- * ACCEPTED or stored. (Not "never reached the server": the server necessarily received enough of
2439
- * it to reject it. The distinction matters precisely here, because this helper exists to separate
2440
- * provably-not-stored from possibly-stored, and the looser phrasing overstates the very thing
2441
- * being measured.) {@link isPermissionDenied} deliberately does not look at the operation: it exists to
2442
- * separate "denied" from "service down", and that answer is the same either way. The operation
2443
- * matters enormously to a caller that reports *delivery*, because a JetStream publish is
2444
- * request/PubAck and the subscription half is the reply inbox — a denial THERE rejects
2445
- * `js.publish()` while the stream may already hold the message. Verified against a live broker: a
2446
- * user allowed to publish but denied its `_INBOX` subscription got
2447
- * `Permissions Violation for Subscription to "_INBOX.….*"` back from `js.publish()`, and an
2448
- * unrestricted observer then read `messages: 1` off the stream.
2449
- *
2450
- * Note what is deliberately NOT accepted: the untyped text fallback above. A permission-shaped
2451
- * message string carries no operation, so it cannot prove non-delivery, and guessing "publish"
2452
- * from wording would reintroduce exactly the false certainty this exists to prevent. Anything not
2453
- * provably a publish denial is unknown, and a caller reporting delivery must fail toward
2454
- * "I could not confirm" rather than toward "it did not happen" — the costly mistake is telling
2455
- * someone to re-send a message that was in fact stored. */
2456
- export declare function isPublishPermissionDenied(e: unknown): boolean;
2457
- /** Whether a server list dials over websocket: the FIRST entry's scheme decides (one list, one
2458
- * transport — a mixed tcp+ws list would race two transports over one identity). */
2459
- export declare function wsServers(servers: string): boolean;
2460
- /** Default probe budget by TRANSPORT. 1s was tuned for the loopback/LAN TCP brokers every local
2461
- * probe dials; a ws(s) broker is by definition published through an HTTPS edge (CDN tunnel,
2462
- * reverse proxy), where TLS + upgrade + INFO + the auth round-trip routinely exceeds 1s cold —
2463
- * measured ~60% spurious "not reachable" against a Cloudflare-fronted broker. Callers passing an
2464
- * explicit `timeoutMs` are untouched.
2465
- *
2466
- * EXPORTED because a caller that judges a probe by WHEN it answered has to compare against the
2467
- * deadline this function actually handed the probe. The delivery watchdog does exactly that, and
2468
- * hardcoding 1000 there silently misread every ws broker: honest refusals arrive at 2-5s, past a
2469
- * budget that was never theirs, and would be classified as this process's starvation rather than
2470
- * the server's refusal. The budget and the judgment must come from one place. */
2471
- export declare function defaultProbeTimeoutMs(servers: string): number;
2472
- /** Pick the dial function by SCHEME: `ws://`/`wss://` servers go through nats-core's
2473
- * `wsconnect` (the websocket transport - e.g. a broker published through an HTTPS edge at
2474
- * `wss://host/path`), everything else through the TCP transport. The websocket dial OWNS its
2475
- * transport options: a required TLS connection refuses any `ws://` target before dialing.
2476
- * `wss://` performs TLS itself, and the w3c transport refuses a `tls` block outright
2477
- * ("'tls' is not configurable"), so the block is removed after that check.
2478
- * A TCP dial that requires TLS to one IP address names that address as the host its certificate
2479
- * must cover (see {@link withDialedTlsHost}). */
2480
- export declare function dialerFor(servers: string): typeof connect;
2481
- /** Whether a failed connect was the server refusing these credentials: a server answered, so it is
2482
- * up. The same errors {@link isReachable} reads as up after its own authenticated connect. */
2483
- export declare function isAuthRejection(e: unknown): boolean;
2484
- /** Whether a NATS server is *running* at `servers`. With NO creds this is a SILENT plaintext
2485
- * liveness check ({@link tcpInfoProbe}): it reads the server's pre-auth `INFO` greeting and closes
2486
- * WITHOUT authenticating, so a live broker (open OR auth — INFO precedes auth) returns true while
2487
- * emitting no broker auth-error log. It may return false for a TLS-first listener — the credless
2488
- * probe is plaintext-only. With creds/token/tls supplied it is instead the AUTHORITATIVE identity
2489
- * check: a real authenticated connect, true on success AND on an auth rejection (a server that
2490
- * refuses these creds is still up — so the caller surfaces the real auth failure, and `up` won't
2491
- * start a duplicate on the bound port). Only a genuine connection failure (refused/timeout) is false. */
2492
- export declare function isReachable(servers?: string, opts?: AuthOpts & {
2493
- timeoutMs?: number;
2494
- }): Promise<boolean>;
2495
- /** What a connect attempt told us about the server — the distinction {@link isReachable} flattens.
2496
- * `auth-required` means a server answered but rejected these creds (so it IS up); `stale-auth`
2497
- * means the PRESENTED CREDENTIAL ITSELF is dead — expired by its bounded lifetime, either because
2498
- * the broker said "authentication expired" or because the cred is LOCALLY PROVABLY expired (its own
2499
- * JWT `exp` is past). The local check is decided without a round-trip, so a slow or failed connect
2500
- * never downgrades a dead cred to `unreachable`; the repair is `doctor auth` either way, never a
2501
- * registry prune (the D5 credential-death event). `unreachable` means nothing usable answered and
2502
- * the cred is not provably dead (refused / timeout / a stale registry entry). `timeout` means the
2503
- * dial ran out of its own budget before anything conclusive came back — never a trust or credential
2504
- * verdict, just "try again with more time" (#851). `inferred` marks an `auth-required` read from
2505
- * the broker's greeting rather than from a rejection: the greeting asked for auth and the handshake
2506
- * was then reset. The greeting is unauthenticated, so that verdict may name a failure but must never
2507
- * be grounds for deleting state. */
2508
- export type ProbeResult = {
2509
- ok: true;
2510
- } | {
2511
- ok: false;
2512
- reason: "auth-required";
2513
- inferred?: true;
2514
- } | {
2515
- ok: false;
2516
- reason: "stale-auth";
2517
- } | {
2518
- ok: false;
2519
- reason: "unreachable";
2520
- } | {
2521
- ok: false;
2522
- reason: "tls-unsupported";
2523
- } | {
2524
- ok: false;
2525
- reason: "timeout";
2526
- };
2527
- /** Like {@link isReachable}, but distinguishes "up but won't take these creds" from "nothing there".
2528
- * `spawn` needs the difference: auth-required → name the trust dir + next step; unreachable → the
2529
- * mesh is down (prune the stale entry, tell the user to `cotal up`). Pass `creds` to confirm a
2530
- * specific identity is accepted (`ok`); omit them to probe mere liveness (an auth broker answers
2531
- * `auth-required`, which still proves it's up). */
2532
- export declare function probeConnect(server?: string, opts?: AuthOpts & {
2533
- timeoutMs?: number;
2534
- }): Promise<ProbeResult>;
2535
2025
  //# sourceMappingURL=endpoint.d.ts.map