@cotal-ai/core 0.167.0 → 0.169.0

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.
Files changed (81) hide show
  1. package/dist/agent-file.d.ts.map +1 -1
  2. package/dist/agent-file.js +12 -9
  3. package/dist/agent-file.js.map +1 -1
  4. package/dist/connector-setup.d.ts +2 -0
  5. package/dist/connector-setup.d.ts.map +1 -1
  6. package/dist/connector.d.ts +8 -11
  7. package/dist/connector.d.ts.map +1 -1
  8. package/dist/control-exchange.d.ts +114 -0
  9. package/dist/control-exchange.d.ts.map +1 -0
  10. package/dist/control-exchange.js +416 -0
  11. package/dist/control-exchange.js.map +1 -0
  12. package/dist/endpoint-call.d.ts +6 -3
  13. package/dist/endpoint-call.d.ts.map +1 -1
  14. package/dist/endpoint-call.js +30 -14
  15. package/dist/endpoint-call.js.map +1 -1
  16. package/dist/endpoint-delivery-plane.d.ts +337 -0
  17. package/dist/endpoint-delivery-plane.d.ts.map +1 -0
  18. package/dist/endpoint-delivery-plane.js +1291 -0
  19. package/dist/endpoint-delivery-plane.js.map +1 -0
  20. package/dist/endpoint-envelope.d.ts +2 -1
  21. package/dist/endpoint-envelope.d.ts.map +1 -1
  22. package/dist/endpoint-envelope.js +9 -3
  23. package/dist/endpoint-envelope.js.map +1 -1
  24. package/dist/endpoint-history.d.ts +370 -0
  25. package/dist/endpoint-history.d.ts.map +1 -0
  26. package/dist/endpoint-history.js +969 -0
  27. package/dist/endpoint-history.js.map +1 -0
  28. package/dist/endpoint-inbound.d.ts +10 -0
  29. package/dist/endpoint-inbound.d.ts.map +1 -0
  30. package/dist/endpoint-inbound.js +28 -0
  31. package/dist/endpoint-inbound.js.map +1 -0
  32. package/dist/endpoint-provenance.d.ts +11 -0
  33. package/dist/endpoint-provenance.d.ts.map +1 -0
  34. package/dist/endpoint-provenance.js +20 -0
  35. package/dist/endpoint-provenance.js.map +1 -0
  36. package/dist/endpoint-serve.d.ts +11 -1
  37. package/dist/endpoint-serve.d.ts.map +1 -1
  38. package/dist/endpoint-serve.js +43 -14
  39. package/dist/endpoint-serve.js.map +1 -1
  40. package/dist/endpoint-subjects.d.ts +3 -0
  41. package/dist/endpoint-subjects.d.ts.map +1 -1
  42. package/dist/endpoint-subjects.js +3 -0
  43. package/dist/endpoint-subjects.js.map +1 -1
  44. package/dist/endpoint.d.ts +80 -252
  45. package/dist/endpoint.d.ts.map +1 -1
  46. package/dist/endpoint.js +248 -2027
  47. package/dist/endpoint.js.map +1 -1
  48. package/dist/index.d.ts +2 -1
  49. package/dist/index.d.ts.map +1 -1
  50. package/dist/index.js +4 -1
  51. package/dist/index.js.map +1 -1
  52. package/dist/launch-material.d.ts +9 -3
  53. package/dist/launch-material.d.ts.map +1 -1
  54. package/dist/launch-material.js +22 -2
  55. package/dist/launch-material.js.map +1 -1
  56. package/dist/provision-jwt.d.ts +518 -0
  57. package/dist/provision-jwt.d.ts.map +1 -0
  58. package/dist/provision-jwt.js +641 -0
  59. package/dist/provision-jwt.js.map +1 -0
  60. package/dist/provision-permissions.d.ts +72 -0
  61. package/dist/provision-permissions.d.ts.map +1 -0
  62. package/dist/provision-permissions.js +2015 -0
  63. package/dist/provision-permissions.js.map +1 -0
  64. package/dist/provision-resources.d.ts +66 -0
  65. package/dist/provision-resources.d.ts.map +1 -0
  66. package/dist/provision-resources.js +61 -0
  67. package/dist/provision-resources.js.map +1 -0
  68. package/dist/provision-server-config.d.ts +115 -0
  69. package/dist/provision-server-config.d.ts.map +1 -0
  70. package/dist/provision-server-config.js +169 -0
  71. package/dist/provision-server-config.js.map +1 -0
  72. package/dist/provision.d.ts +19 -707
  73. package/dist/provision.d.ts.map +1 -1
  74. package/dist/provision.js +4 -2860
  75. package/dist/provision.js.map +1 -1
  76. package/dist/remote-manager-authority.d.ts +1 -1
  77. package/dist/run-journal.d.ts +2 -0
  78. package/dist/run-journal.d.ts.map +1 -1
  79. package/dist/run-journal.js +1 -1
  80. package/dist/run-journal.js.map +1 -1
  81. package/package.json +5 -1
@@ -1,713 +1,25 @@
1
- import type { BrokerTransport } from "./broker-tls.js";
2
- import { type DeprovisionTarget } from "./subjects.js";
3
- import { type EpCapability } from "./endpoint-grants.js";
4
- import { type EpServeGrant, type EpIssuanceGate } from "./endpoint-service.js";
5
- import { type ServiceConnectionBinding } from "./service-gate.js";
6
- import { type EpCaller } from "./endpoint-subjects.js";
7
- import { type IssuanceSeam, type ListingBinding, type ListingSeam } from "./issued-authority.js";
8
- import { type RunDriverGrantArgs, type RunOperatorGrantArgs } from "./run-driver-grants.js";
9
- import { type EnvironmentManagerGrantPin } from "./environment-manager-grants.js";
10
- import { type Identity } from "./identity.js";
11
- import { type BackupPermissionScope, type RestorePermissionScope } from "./backup.js";
12
- /** Cred profiles. Each profile has an explicit permission arm and a lifetime classification. */
13
- export type Profile = "agent" | "manager-caller" | "observer" | "admin" | "supervisor" | "provisioner" | "deprovisioner" | "retirement-requester" | "lifecycle-executor" | "endpoint-serve-executor" | "operator" | "purger" | "backup" | "restore" | "delivery" | "membership-rw" | "probe" | "channel-writer" | "channel-purger" | "teardown" | "membership-store-recreate" | "issued-store-recreate" | "control-caller-privileged" | "control-caller-admin" | "deployer" | "endpoint-serve" | "goal-writer" | "session-caller" | "dm-reader" | "session-serving" | "session-ledger" | "run-driver" | "run-mediator" | "run-operator" | "endpoint-evictor" | "issuer" | "registry-reader" | "run-admitter" | "transfer-writer" | "transfer-reader" | "remote-manager" | "environment-bootstrap" | "environment-manager-supervisor" | "environment-manager-executor" | "environment-manager-goal-writer";
14
- export type CredentialLifetimeClass = "standing-renewable" | "rotation-renewed" | "one-shot" | "static-operator-managed" | "mixed";
15
- export type CredentialKind = Profile | "membership-observer" | "account-census" | "connection-evictor";
16
- export interface CredentialLifetimePolicy {
17
- class: CredentialLifetimeClass;
18
- /** Default max age at mint. Undefined = the profile mints no default exp. */
19
- defaultTtlSeconds?: number;
20
- renewalOwner?: string;
21
- note: string;
22
- }
23
- /** The broker's pre-auth control-line cap, in bytes (`max_control_line` in the generated config —
24
- * `openServerConfig` and `serverConfig` below both render this literal, so the cap and the
25
- * mint-time bound derived from it below can never drift). 64 KiB clears a many-channel agent
26
- * JWT (~4-8 KB) with wide margin while keeping the pre-auth allocation ~16x tighter than 1 MB
27
- * under connection flooding (the CONNECT line is parsed BEFORE auth). */
28
- export declare const MAX_CONTROL_LINE_BYTES = 65536;
29
- /** The fixed bytes a NATS client wraps around the `jwt` field on the CONNECT protocol line, over
30
- * and above the JWT itself: the JSON object's other keys (`nkey`, `sig`, `name`, `lang`,
31
- * `version`, `protocol`, `verbose`, `pedantic`, `no_responders`, `headers`), their values, and
32
- * the surrounding braces/quotes/commas. Measured live (nats-server `-DV`, the trace of the raw
33
- * protocol) on a real connect with the nats.js v3 client: a control-name credential produced a
34
- * 5,104-byte JWT inside a 5,291-byte CONNECT line — 187 bytes of envelope, reproduced twice.
35
- * Rounded up generously (>2.5x) to absorb client/library variation this repo does not control. */
36
- export declare const CONNECT_ENVELOPE_OVERHEAD_BYTES = 512;
37
- /** The mint-time budget for a user JWT's byte size: every composition that inflates the JWT (a
38
- * long single channel, many channels, the per-agent event channel, any grant a later change
39
- * adds) is priced against the SAME number, because the credential is what the client sends on
40
- * the CONNECT line and the CONNECT line is what the broker caps — not any one contributor to it.
41
- * `assertValidName`/`assertValidChannel` bound one input each; this bounds the OUTPUT, closing
42
- * the gap between "every individual grant is legal" and "the composed credential still fits"
43
- * (issue #375's review finding: six distinct 4096-char channels, each individually accepted,
44
- * minted a JWT the broker would silently drop). */
45
- export declare const MAX_MINTED_JWT_BYTES: number;
46
- /** Bounded lifetime for `standing-renewable` credentials whose renewal owner is ONLINE:
47
- * the holder (or its launcher) re-mints at 75% of the lifetime via the endpoint's creds-source seam,
48
- * so a copied cred is broker-dead within a day while renewal never involves an operator. 24h keeps
49
- * the remaining-25% loud-failure window at ~6h — wide enough to notice and repair before expiry. */
50
- export declare const STANDING_RENEWABLE_TTL_SEC: number;
51
- /** Bounded lifetime for the `rotation-renewed` $SYS credentials (membership-observer + connection-
52
- * evictor). They are NOT online-renewable (the $SYS seed dies at end of `up`), so this exp is the
53
- * credential-death horizon: a copied observer/evictor cred becomes broker-dead after it, and the
54
- * operator is expected to have run a coordinated system-account rotation + broker restart within it
55
- * (the doctor surface warns ahead). 30 days balances "copied cred eventually dies" against
56
- * a comfortable monthly rotation cadence; tune here as one named knob. */
57
- export declare const ROTATION_RENEWED_TTL_SEC: number;
58
- /** The credential lifetime matrix. This is intentionally centralized so every new mint profile must classify its
59
- * credential-death behavior instead of silently inheriting non-expiring static creds. */
60
- export declare const CREDENTIAL_LIFETIMES: Record<CredentialKind, CredentialLifetimePolicy>;
61
- export declare function credentialLifetime(kind: CredentialKind): CredentialLifetimePolicy;
62
- /** A local credential file's health, by the SAME convention the renewal seam runs on: renewal is due
63
- * at 75% of the iat→exp lifetime, so `near-expiry` means "past the point where a healthy renewal
64
- * owner would already have re-signed this" — the doctor's yellow. `unreadable` (not a throw) is for
65
- * a corrupt/spliced file: the doctor must render it red with a repair, not crash the diagnosis. */
66
- export type CredHealthState = "healthy" | "near-expiry" | "expired" | "unbounded" | "unreadable";
67
- export interface CredHealth {
68
- state: CredHealthState;
69
- /** Issue time (epoch sec) — the "last renewal" timestamp for reminted creds. */
70
- iat?: number;
71
- exp?: number;
72
- /** The 75%-of-lifetime renewal point (epoch sec); past it = near-expiry. */
73
- renewAt?: number;
74
- /** Present only for `unreadable`. */
75
- error?: string;
76
- }
77
- export declare function inspectCredHealth(creds: string, nowSec?: number): CredHealth;
78
- /** BROKER-level trust: the operator root and the system account. A nats-server trusts exactly ONE
79
- * operator and one system account, so this is the per-BROKER authority, not a per-space one. With
80
- * many spaces on one broker every space's accounts are signed by this one operator.
81
- *
82
- * `sys.signingSeed` is minting capability for system-account users (the membership observer and the
83
- * connection evictor). It is in-memory only on a fresh {@link createBrokerAuth} and is NOT written
84
- * by the local filesystem persistence, so on that path a space added after first boot cannot mint
85
- * its `$SYS` users. A hosted composition that needs incremental space provisioning must hold this
86
- * seed in a BROKER-scoped secret store (never a tenant-scoped one, which would give each tenant its
87
- * own operator or duplicate the seed and so recreate multiple owners). */
88
- export interface BrokerAuth {
89
- operator: {
90
- seed: string;
91
- jwt: string;
92
- };
93
- sys: {
94
- pub: string;
95
- jwt: string;
96
- signingSeed?: string;
97
- };
98
- /** Monotonic generation of the system-account authority. {@link rotateSystemAccount} bumps it
99
- * IN MEMORY (each rotation is the next generation of the value it derived from); persistence
100
- * (`saveBrokerAuth`) then only accepts a sys-changing write that is the DIRECT successor of the
101
- * current record, refusing anything else as stale. Absent = 0 (in-memory creates and
102
- * pre-generation records). The JWT `iat` cannot carry this ordering — it is second-resolution,
103
- * so two generations minted within one second are unordered by it. */
104
- gen?: number;
105
- }
106
- /** SPACE-level trust: one space's data account, signed by its broker's operator. This is the only
107
- * part of a space's trust material a space actually OWNS; broker trust is referenced, never owned
108
- * (a per-space restore or rotation must not be able to move the broker's root). The `signingSeed`
109
- * is the sensitive provisioner secret that mints this account's users. */
110
- export interface SpaceAccountAuth {
111
- space: string;
112
- account: {
113
- pub: string;
114
- seed: string;
115
- jwt: string;
116
- signingSeed: string;
117
- signingPub: string;
118
- };
119
- }
120
- /** The COMPOSED read view of one space's full trust chain: broker authority plus that space's
121
- * account. Deliberately structurally identical to the single-space shape, so the many
122
- * existing readers compose rather than churn.
123
- *
124
- * This is a read adapter, never a persistence authority: it is produced by loading the two
125
- * persisted records and validating their binding. Writing a composed value back as one document
126
- * would let a mutation made through space A resurrect a stale broker copy when space B next loads
127
- * it, which is exactly the ownership bug the split exists to prevent. */
128
- export interface SpaceAuth extends BrokerAuth, SpaceAccountAuth {
129
- }
130
- /** Compose the read view from its two persisted authorities. Fails loud when the space account was
131
- * not signed by THIS broker's operator: a self-consistent account signed by a FOREIGN operator is
132
- * perfectly valid on its own and would otherwise be rendered into the resolver as untrusted trust. */
133
- export declare function composeSpaceAuth(broker: BrokerAuth, spaceAccount: SpaceAccountAuth): SpaceAuth;
134
- /** The binding check behind {@link composeSpaceAuth} and registry admission: this space's data
135
- * account JWT must be issued by this broker's operator identity. */
136
- export declare function assertAccountSignedByBroker(broker: BrokerAuth, spaceAccount: SpaceAccountAuth): void;
137
- /** Reduce a {@link SpaceAuth} to just the material a *minting* host needs: `space`,
138
- * `account.pub`, and `account.signingSeed` (the only fields {@link mintCreds} reads).
139
- * The operator root-of-trust, system account, and the account's own seed are blanked.
140
- *
141
- * This is the file you hand a manager that should mint per-agent creds but must never
142
- * hold the operator key — e.g. a containerized team. A leaked stripped file only lets
143
- * someone mint *users within this one account*, which the account boundary already
144
- * contains; it cannot mint new accounts or touch the system account. */
145
- export declare function stripSpaceAuth(auth: SpaceAuth): SpaceAuth;
146
- /** The user public keys a data-account JWT revokes, each with the Unix second it was revoked at. The
147
- * broker refuses a user JWT for that key issued at or before that second. */
148
- export declare function accountRevocations(accountJwt: string): Record<string, number>;
149
- /** Re-issue the data-account JWT with the user key `userPub` revoked at `at` (Unix seconds), keeping
150
- * every other claim. A key already revoked keeps its first time and the auth is returned unchanged.
151
- * The broker applies it when it next loads its configuration. */
152
- export declare function revokeAccountUser(auth: SpaceAuth, userPub: string, at: number): Promise<SpaceAuth>;
153
- /** Re-issue an account JWT that this broker's operator signed so the account serves nobody: every
154
- * user key issued at or before `at` (Unix seconds) is revoked, and the account admits no client or
155
- * leaf connection, so a user minted later is refused as well. Every other claim is kept, so the
156
- * account's JetStream data stays where it is. Push the result with {@link pushAccountClaim} to stop
157
- * a space on a running full-resolver broker; its live connections close without a reload. */
158
- export declare function retireAccountClaim(broker: BrokerAuth, accountJwt: string, at: number): Promise<string>;
159
- /** Rotate the SYSTEM account and re-issue the operator JWT so persisted system-account users (currently
160
- * `membership-observer`) become broker-dead once the broker loads the returned auth. The fresh
161
- * `sys.signingSeed` is intentionally in-memory only; callers must mint replacement observer creds before
162
- * persisting via `saveSpaceAuth`, which strips the seed again. */
163
- export declare function rotateSystemAccount(auth: SpaceAuth): Promise<SpaceAuth>;
164
- /** Generate a fresh BROKER trust root: operator → system account. One per broker, NOT one per space.
165
- * `label` names the operator (cosmetic, but it lands in the operator JWT); multi-space brokers pass
166
- * a broker label, and the single-space compatibility path passes the space name so existing
167
- * operator names are unchanged.
168
- *
169
- * The returned `sys.signingSeed` is the ONLY window in which system-account users (the membership
170
- * observer and the connection evictor) can be minted, because the local filesystem persistence does
171
- * not write it. Callers that need to add spaces later must retain it in a broker-scoped store. */
172
- export declare function createBrokerAuth(label: string): Promise<BrokerAuth>;
173
- /** Generate one space's data account (+ signing key), signed by an EXISTING broker operator. This is
174
- * the per-tenant half of provisioning: call it once per space against the same {@link BrokerAuth}
175
- * to put many spaces on one broker, each in its own NATS account. Key generation and JWT
176
- * construction stay with NATS; the existing native signer derives public keys and signs. */
177
- export declare function createSpaceAccountAuth(broker: BrokerAuth, space: string): Promise<SpaceAccountAuth>;
178
- /** Generate a fresh operator → account(+signing key) → system-account chain for a space.
179
- * The single-space composition of {@link createBrokerAuth} + {@link createSpaceAccountAuth}: one
180
- * broker whose only tenant is this space. */
181
- export declare function createSpaceAuth(space: string): Promise<SpaceAuth>;
182
- /** An issuance's binding on a mint (SPEC 13.15): the generation, the token naming its accepted
183
- * row, and whether the ceiling carries the registry's `endpoints` row. That flag is recorded with
184
- * the issuance so a renewal mints the same ceiling it was issued with. */
185
- export interface IssuedBinding {
186
- readonly generation: string;
187
- readonly acceptedToken: string;
188
- readonly listing?: true;
189
- }
190
- /** Options shaping a minted user's permissions. */
191
- export interface MintOpts {
192
- /** Trusted issuance restriction: exclude the tool-payload publish rail when false. */
193
- eventPayloads?: boolean;
194
- /** The owner+actor principal to mint for. Omitted ⇒ the no-login dev default (owner `"local"`, actor
195
- * = the connection id) via {@link principalOf}. User mode supplies the derived owner + ledger actor. */
196
- principal?: {
197
- owner: string;
198
- actor: string;
199
- };
200
- /** Read ACL — channels an "agent" MAY read (the agent file's `allowSubscribe`, already resolved
201
- * by the caller). Minted as per-channel single-filter history-consumer create grants
202
- * (`CONSUMER.CREATE.<CHAT>.<chathist_id>.<chat.*.ch>`) — the broker boundary on chat **history**
203
- * reads (join-backfill / focus-recall). Each is run through the chat-subject builder so a
204
- * wildcard subtree `team.>` becomes `chat.*.team.>`. Omitted or empty ⇒ NO channel read rows at
205
- * all (the cred carries no chat history grant and no `chat.*.<ch>` sub row); DM, presence,
206
- * anycast and the control rails are unaffected. The live read is the agent's own native
207
- * `sub.allow` over `chat.*.<channel>` (also minted from this list, below). */
208
- allowSubscribe?: string[];
209
- /** Post ACL — channels an "agent" may publish to (the agent file's `allowPublish`, already
210
- * resolved by the caller). Each becomes a `chat.<id>.<ch>` publish grant. **Default-deny**:
211
- * omitted/empty ⇒ no chat publish grant at all — publishing must be declared. */
212
- allowPublish?: string[];
213
- /** The agent's role — scopes its TASK-queue consumer to svc_<role>. */
214
- role?: string;
215
- /** Capabilities declared in the agent file (e.g. `"spawn"`). Each gates a set of manager ep
216
- * caller rows in {@link permissionsFor}: `spawn` → {@link spawnCallerCapabilities}, `run` →
217
- * {@link runCallerCapabilities}, `admin` → the admin {@link operatorInstrumentCapabilities} set.
218
- * Default-deny when absent — nats-server rejects the publish, no handler involved. */
219
- capabilities?: string[];
220
- /** v0.4 endpoint request capabilities (SPEC §13.9 caller rows): each mints its exact
221
- * request-publish rows (+ optional journal-append row) and, when any is present, the
222
- * caller's own reply-rail read row. Requires {@link MintOpts.lifecycleUid} — the rows pin
223
- * the full caller triple. Default-deny when absent. */
224
- endpointCapabilities?: EpCapability[];
225
- /** `manager-caller` profile only: the one manager instance every request row pins. */
226
- managerInstanceId?: string;
227
- /** The caller's lifecycle UID (SPEC §13.1), minted by the managing authority BEFORE the
228
- * entity is reachable. REQUIRED with `endpointCapabilities` — every endpoint-rail row
229
- * forge-locks it as the third caller token. */
230
- lifecycleUid?: string;
231
- /** v0.4 SERVE identity (SPEC §13.9 serve rows), `endpoint-serve` profile ONLY: mints the
232
- * instance's queue-qualified class subscribes (no plain class-rail subscribe exists on any
233
- * credential), the plain scatter and own `inst` rails for the FULL registered command set
234
- * plus the derived `describe`, the own epoch-pinned timer-fire read, and the epoch-pinned
235
- * egress (reply/epe/ept-schedule/epr). MUST be the branded ARTIFACT `authorizeServeGrant`
236
- * returned — a raw literal, a structural copy, or a diverging value refuses at the mint, and
237
- * the mint context is bound to the artifact (same space; the minted principal IS the
238
- * registered owner). The freshness FENCE is the durable issuance gate ({@link serveIssuance}
239
- * / SPEC §13.1), not this artifact. Every other profile refuses it (a serve credential is
240
- * per-instance, never an agent-baseline cred). The `$JS.API` bind rows (effects/pool
241
- * durables) ride `effectsBindGrants`/`poolOwnerBindGrants`, not this subject-space builder. */
242
- endpointServe?: EpServeGrant;
243
- /** v0.4 SERVE mint fence (SPEC §13.1), `endpoint-serve` profile ONLY and REQUIRED there: the
244
- * durable, single-key issuance gate whose revision-pinned CAS `mintCreds` must WIN to release
245
- * the serve credential. Both the takeover and re-registration barriers freeze this same gate,
246
- * so a mint racing either loses the CAS and releases nothing. Production wires it to the
247
- * credential ledger's endpoint family `epgate.<endpoint>.<instanceId>` (the auth
248
- * implementation's `kvServeIssuanceGate`); a test provides a faithful CAS fake. */
249
- serveIssuance?: EpIssuanceGate;
250
- /** Delivery-daemon shard seam (`delivery` profile only). N=1 is the only operating mode; these do
251
- * not change permissions in this build (the daemon owns the whole space at N=1). Present so the
252
- * N>1 follow-up is a small diff. Default `{0,1}`. */
253
- shard?: number;
254
- shards?: number;
255
- /** The departed LIFECYCLE whose footprint a `deprovisioner` cred may tear down: the target's
256
- * principal PLUS the exact lifecycle uid being retired (SPEC §13.1). REQUIRED for that profile (it
257
- * throws without one): the grants are pinned to exactly this incarnation's
258
- * `dm_<o>-<a>-<uid>`/`dlv_<o>-<a>-<uid>` durables + `<o>.<a>.<uid>` ACL row, so a leaked or
259
- * REPLAYED deprovisioner cred can delete ONE retired incarnation's footprint and nothing else —
260
- * never a peer's, never the role-shared `svc_<role>`, and structurally never a same-alias
261
- * successor's (its names carry a different uid). Ignored by every other profile. */
262
- deprovisionTarget?: DeprovisionTarget;
263
- /** `retirement-requester` profile only: the REQUESTING CALLER TRIPLE (the current space-manager's
264
- * own `owner`/`actor`/`uid`) whose auth-endpoint request subject the credential may publish, and
265
- * whose reply rail it may read. The subject IS the attribution: the auth plane's rail derives
266
- * the caller principal from the subject the broker admitted, and refuses unless the serve
267
- * registration the request names belongs to THAT principal — so a requester cannot be authorized
268
- * by another instance's registration.
269
- *
270
- * The `uid` is why this carries a triple and not the pre-#350 `{owner, actor}` pair: the `ctl`
271
- * rail's two-token subject could express only a recyclable alias, while the `ep` caller triple
272
- * is `<owner>.<actor>.<uid>` and the grant pins all three. Ignored by every other profile. */
273
- retirementRequester?: {
274
- owner: string;
275
- actor: string;
276
- uid: string;
277
- /** The ONE incarnation this credential may ask to retire. It rides the SUBJECT as the
278
- * `handle` target, so the grant pins it: a leaked requester cannot be re-aimed. */
279
- target: {
280
- owner: string;
281
- actor: string;
282
- lifecycleUid: string;
283
- };
284
- };
285
- /** `lifecycle-executor` profile only (the static §13.1 executor): the ONE incarnation
286
- * whose lifecycle-state keys this credential may write — the head `lifecycle.<owner>.<actor>`,
287
- * the reservation `uid.<lifecycleUid>`, the gate `gate.<lifecycleUid>`, the ledger family
288
- * `cred.<lifecycleUid>.>`, and the manager's durable slot row `mgrslot.<owner>.<alias>`.
289
- * REQUIRED for that profile (it throws without one). EVERY key is DERIVED inside the profile
290
- * from (owner, actor, lifecycleUid, alias) — none is a caller-supplied literal — so the pin is
291
- * coherent by construction and a leaked executor cred can move exactly one incarnation's state
292
- * machine and nothing else. Ignored by every other profile. */
293
- lifecycleExecutor?: {
294
- owner: string;
295
- actor: string;
296
- lifecycleUid: string;
297
- alias: string;
298
- };
299
- /** `endpoint-serve-executor` profile only: the ONE endpoint instance whose
300
- * endpoint-serve state this credential may write — the endpoint gate `epgate.<endpoint>.
301
- * <instanceId>` (the registration barrier's freeze/reopen CAS + the provisioner create) and the
302
- * serving ledger family `epcred.<endpoint>.<instanceId>.>` (the mint fence's stage + the barrier's
303
- * revoke). REQUIRED for that profile. Every key is DERIVED inside the profile from
304
- * (endpoint, instanceId) — none is a caller literal — so the manager drives the gate CAS + serve
305
- * mint through THIS scoped executor and nothing else (the standing seed connection never writes
306
- * the epgate or the epcred family). Ignored by every other profile. */
307
- endpointServeExecutor?: {
308
- endpoint: string;
309
- instanceId: string;
310
- };
311
- /** `goal-writer` profile only (spawn-as-action): the endpoint whose action goals this
312
- * standing connection may bind + commit ({@link goalWriterGrants}). REQUIRED for that profile;
313
- * ignored by every other. */
314
- goalWriter?: {
315
- endpoint: string;
316
- };
317
- /** `session-caller` profile only: the ONE §13.6 session whose two eps rails this
318
- * credential may use — the serving endpoint, the fresh sessionId, and the serving epoch. REQUIRED
319
- * for that profile; ignored by every other. The rows pin all three, so the cred authorizes
320
- * exactly that session's `in`+`out` and nothing else. */
321
- sessionCaller?: {
322
- endpoint: string;
323
- sessionId: string;
324
- epoch: number;
325
- };
326
- /** `session-serving` profile only: the ONE §13.6 session this SERVING credential may
327
- * serve — same three coordinates as {@link sessionCaller}, with the rail directions swapped.
328
- * REQUIRED for that profile; ignored by every other. The `session-ledger` profile takes no pin
329
- * at all: it holds no rail, so it has nothing to pin. */
330
- sessionServing?: {
331
- endpoint: string;
332
- sessionId: string;
333
- epoch: number;
334
- };
335
- /** `run-driver` profile only (SPEC 14.6): the ONE run this credential drives, the takeover attempt
336
- * it is minted for (names the replay durable), and the driving instance's id and epoch (the
337
- * coordinates its timer schedules are addressed by). REQUIRED for that profile; ignored by every
338
- * other. The ep caller triple is DERIVED from the run id ({@link runDriverCaller}), never supplied. */
339
- runDriver?: RunDriverGrantArgs;
340
- /** Trusted host only: the run and takeover whose journal authorizes its effects. */
341
- runMediator?: RunDriverGrantArgs;
342
- /** `run-operator` profile only (SPEC 14.3): the ONE endpoint whose runs this credential may read,
343
- * the takeover id its journal replays are named by, and, for the answering half of a
344
- * `run-answer`, the ONE checkpoint token its answer and settle writes are pinned to. REQUIRED
345
- * for that profile; ignored by every other. */
346
- runOperator?: RunOperatorGrantArgs;
347
- /** `remote-manager` profile only: the server-derived owner, fixed server-selected actor, and the
348
- * ONE locally-selected manager instance id this credential may supervise. REQUIRED for that profile. The builder pins its
349
- * manager lease/presence and same-owner provisioning resources; no caller-supplied subject rows
350
- * or profile fallback are accepted. */
351
- remoteManager?: {
352
- instanceId: string;
353
- owner: string;
354
- actor: string;
355
- };
356
- /** Fixed environment profiles only. Host-derived pins confer no admission authority.
357
- * These profiles require explicit expiresAt, no later than this admission's expiry. */
358
- environmentManager?: EnvironmentManagerGrantPin;
359
- /** `deployer` profile only: which v0.4 ep instrument set its `launch`/`ps` rows carry. Defaults
360
- * to `"admin"` (the static operator's ephemeral deploy cred). The user-mode `deployer` VIEW
361
- * mints `"privileged"` instead, so a spawn-scoped deploy reaches the manager where its
362
- * owner-equality launch authorization governs — never the admin any-mode reach. Ignored by
363
- * every other profile. */
364
- controlTier?: "privileged" | "admin";
365
- /** Override the profile default lifetime. Internal/test hook; command surfaces should prefer the
366
- * centralized {@link CREDENTIAL_LIFETIMES} defaults so profile behavior stays auditable. */
367
- expiresInSeconds?: number;
368
- /** Absolute JWT `exp` timestamp in seconds. Used by cutover/test code that needs already-expired creds. */
369
- expiresAt?: number;
370
- /** Issued authority (SPEC 13.15): mint this credential's ep-rail rows on the VERSIONED rail,
371
- * pinned to `generation`, and grant the per-key read of its accepted row. The issuer chose the
372
- * generation and persisted its evidence before calling; the client chose `acceptedToken` and
373
- * learns the accepted generation by reading that one row after it connects. Taken by the
374
- * profiles that hold caller rails (`agent`, the operator instruments); every other profile
375
- * refuses it. */
376
- issued?: IssuedBinding;
377
- /** A LISTING generation (SPEC 13.15, "Listing issuance"): the credential keeps the legacy rail
378
- * for every row and gains exactly {@link listingGrantRows}. `agent` and `manager-caller` only,
379
- * and never beside {@link MintOpts.issued}, whose own generation carries the listing. */
380
- listing?: ListingBinding;
381
- /** The issuer handles a static `agent` mint decides its listing generation over. The horizon is
382
- * the credential's own expiry, so a mint with no expiry gets no listing generation. */
383
- listingSeam?: ListingSeam;
384
- /** `agent` profile only: the kind of the ledger row the principal was found in, which only the
385
- * auth callout reads (SPEC 13.21). A row of either kind serves its own `agent` endpoint on the
386
- * principal route; an `interactive` row, an actor its person granted directly, also calls its
387
- * owner's agents there with the `owner` word. It never comes from a scope token, which a parent
388
- * could hand to the agents it spawns. A static mint refuses it. */
389
- ledgerKind?: "interactive" | "managed-agent";
390
- /** The durable half of an issuance, REQUIRED beside {@link MintOpts.issued} on {@link mintCreds}:
391
- * the credential is built first, then its evidence is staged create-only, the existing
392
- * finalizer runs, and the attempt activates by CAS at the revision the stage observed; only
393
- * then is the accepted row written and the material returned (SPEC 13.15). `renew` confirms an
394
- * existing generation's ceiling is unchanged and stages nothing. */
395
- issuance?: IssuanceSeam;
396
- /** `run-admitter` profile only: the ONE hosted run whose admission record and revocation marker
397
- * this connection may create. */
398
- runAdmitter?: {
399
- endpoint: string;
400
- runId: string;
401
- submission?: {
402
- caller: import("./endpoint-subjects.js").EpCaller;
403
- id: string;
404
- };
405
- };
406
- /** `transfer-writer` profile only: the ONE object (the transcript's hex digest) in the ONE manager
407
- * instance's transfer bucket this instrument may write. */
408
- transferWriter?: {
409
- instanceId: string;
410
- hex: string;
411
- };
412
- /** `transfer-reader` profile only: the manager instance whose own transfer bucket this reads. */
413
- transferReader?: {
414
- instanceId: string;
415
- };
416
- /** `teardown` profile only: the space's transfer streams, listed before the mint, that this
417
- * teardown may inspect and delete by name ({@link deleteSpace} lists and names them). */
418
- transferStreams?: string[];
419
- /** `backup` profile only: one discriminated inspector or snapshot phase. */
420
- backup?: BackupPermissionScope;
421
- /** `restore` profile only: one discriminated initiate, upload, validate, or checkpoint phase. */
422
- restore?: RestorePermissionScope;
423
- }
424
- /** Options for {@link provisionAgent} — {@link MintOpts} plus the active read set. */
425
- export interface ProvisionOpts extends MintOpts {
426
- /** The active read set: the channels the agent subscribes to (live core-sub) at boot, and whose
427
- * `durable`-class ones the agent self-joins for a Plane-3 backstop at connect (via the delivery
428
- * daemon). Must be ⊆ `allowSubscribe`. Omitted or empty ⇒ no boot channels at all. */
429
- subscribe?: string[];
430
- /** Record this agent's read ACL so it can participate in durable delivery (default true). A durable
431
- * backstop needs the agent's read ACL in the registry — the server-side delivery daemon re-authorizes
432
- * every durable entry against it — written here at provision. Set FALSE for a LIVE-ONLY launcher
433
- * (e.g. a direct foreground `cotal spawn` with no durable intent): no ACL row is written, so the daemon
434
- * refuses to authorize a durable backstop and the agent stays live-only. Boot durable MEMBERSHIP itself
435
- * is not written here — the agent self-joins its durable channels via the daemon's `ctl.delivery` op at
436
- * connect. */
437
- durableMembership?: boolean;
438
- }
439
- /** The privileged onboarding ops a launcher needs at spawn — implemented by a connected, permissive
440
- * endpoint (the manager at `cotal start`/`cotal up`, or a short-lived provisioner that `cotal spawn`
441
- * opens). It pre-creates the agent's own mailboxes and records its read ACL; it does NOT host Plane-3
442
- * delivery (that is the server-side delivery daemon). */
443
- export interface DurableProvisioner {
444
- /** Pre-create the lifecycle's bind-only DM durable (`dm_<owner>-<actor>-<uid>`). The implementation
445
- * captures the DM stream's ACTIVATION FRONTIER (its `last_seq` at first creation) and starts
446
- * delivery at frontier+1 (SPEC §8) — a same-alias successor inherits no predecessor DMs.
447
- * Idempotent PER LIFECYCLE: a re-provision of the same uid keeps the existing durable (and so the
448
- * ORIGINAL frontier — the activation moment does not move on manager restart). */
449
- provisionDmInbox(owner: string, actor: string, lifecycleUid: string): Promise<void>;
450
- /** Pre-create the lifecycle's bind-only Plane-3 DELIVER durable (`dlv_<owner>-<actor>-<uid>`,
451
- * filtered to the lifecycle-scoped `dlv.<owner>.<actor>.<uid>`) so it can BIND its per-member
452
- * durable handoff without holding CONSUMER.CREATE on the DLV stream. */
453
- provisionDlvInbox(owner: string, actor: string, lifecycleUid: string): Promise<void>;
454
- /** Record the lifecycle's read ACL (`allowSubscribe`) in the durable ACL registry, keyed
455
- * `<owner>.<actor>.<lifecycleUid>` (SPEC §13.1) — the same act as baking it into the JWT, persisted
456
- * so the **server-side delivery daemon** can re-authorize the agent's durable entries and validate
457
- * its runtime durable-joins (it holds no in-memory ledger). Replaces the old manager-written boot
458
- * membership: boot durable membership is now the agent SELF-JOINING its durable channels via the
459
- * daemon's `ctl.delivery` op at connect. */
460
- commitAcl(principal: string, lifecycleUid: string, allowSubscribe: string[]): Promise<void>;
461
- /**
462
- * Raise the mint-time ceiling. Only the provisioning path that also remints the JWT.
463
- * Process discipline, not crypto binding — see {@link reissueAcl}.
464
- */
465
- reissueAcl(principal: string, lifecycleUid: string, allowSubscribe: string[]): Promise<void>;
466
- provisionTaskQueue(role: string): Promise<void>;
467
- }
468
- /** The identity a cred is minted for: the owner+actor wire principal PLUS the connection nkey the cred
469
- * authenticates as. The wire grammar, per-agent KV keys, durables and presence key off owner+actor; the
470
- * private reply inbox (`_INBOX_<connId>`) keys off the connection nkey — under the auth callout that is a
471
- * per-connection ephemeral the client always knows, whereas the derived owner is not known pre-connect. */
472
- export interface MintPrincipal {
473
- owner: string;
474
- actor: string;
475
- connId: string;
476
- /** The incarnation's lifecycle UID (SPEC §13.1). REQUIRED for the `agent` profile — its
477
- * dm/dlv/chathist grants are lifecycle-keyed EXACT names, so a credential cannot name another
478
- * incarnation's resources. Other profiles ignore it. */
479
- lifecycleUid?: string;
480
- /** The connection's history-reader id, the key of the observer and admin profiles' reader deletes
481
- * ({@link historyReaderConsumer}). A static mint leaves it unset, because there `connId` is the
482
- * credential's own nkey, which its holder proves by signing. The auth callout sets it to
483
- * {@link calloutReaderId}, because there `connId` is the inbox nonce the client chose. */
484
- readerId?: string;
485
- }
486
- /** Onboard an agent for launch (auth mode): pre-create its bind-only DM (+ Plane-3 DELIVER + role
487
- * TASK) durables, RECORD its read ACL in the durable registry (unless `durableMembership:false`), and
488
- * mint its scoped creds. Live delivery is the agent's own core subscription — there is no per-instance
489
- * chat durable. Boot durable MEMBERSHIP is not written here: the agent self-joins its durable channels
490
- * via the server-side delivery daemon's `ctl.delivery` op at connect. A deliberately live-only
491
- * launcher (`durableMembership:false`, e.g. `cotal spawn --live-only`) gets no ACL row, so the
492
- * daemon never authorizes a durable backstop for it. */
493
- export declare function provisionAgent(provisioner: DurableProvisioner, auth: SpaceAuth, identity: Identity, opts?: ProvisionOpts): Promise<string>;
494
- /** The DURABLE half of agent onboarding, principal-keyed and credential-agnostic: pre-create the
495
- * bind-only DM durable and, when the read ACL is nonempty, the DELIVER durable; record the read ACL;
496
- * ensure the role TASK queue. The static
497
- * path ({@link provisionAgent}) follows it with a mint; the USER-MODE spawn path runs it alone —
498
- * a user agent's credential is its bearer (callout-minted per connect), never a static cred.
499
- * Returns the resolved read ACL so both callers scope from the same computed set. */
500
- export declare function provisionAgentDurables(provisioner: DurableProvisioner, pr: {
501
- owner: string;
502
- actor: string;
503
- lifecycleUid: string;
504
- }, opts?: ProvisionOpts): Promise<string[]>;
505
- /** The role a `role:<r>` capability token names, or `undefined` for any other token. */
506
- export declare function capabilityRole(token: string): string | undefined;
507
- /** The roles whose task queue an agent credential binds: its own role, and the role of each
508
- * `role:<r>` token in its capabilities, which lets it hand that role on (SPEC 13.15). */
509
- export declare function taskRoles(role: string | undefined, capabilities: readonly string[] | undefined): string[];
510
- /** Mint a user creds file for an agent {@link Identity} (its stable id+seed from
511
- * {@link newIdentity}). The account signing key signs over ONLY the public key
512
- * (`fromPublic`) — the agent seed is never part of the signature, it's only folded into
513
- * the resulting creds file. The "agent" profile is scoped to publish only as itself and only to
514
- * its declared `allowPublish` channels (post ACL, default-deny), and to read only within
515
- * `allowSubscribe` (live tail bind-only + per-channel history grants). Every profile is now
516
- * enumerated least-privilege — there is no allow-all cred (the former `manager` is deleted). */
517
- export declare function mintCreds(auth: SpaceAuth, identity: Identity, profile: Profile, opts?: MintOpts): Promise<string>;
518
- /** Issue a host-signed NATS user JWT for a caller-generated nkey. The private seed stays with
519
- * the remote manager. This is deliberately narrower than {@link mintCreds}: only the typed remote
520
- * manager protocol may request it, and every profile still goes through the same permission and
521
- * lifetime builders. It signs with the space account's signing key alone, so a host that holds
522
- * only that key passes no placeholder broker trust. */
523
- export declare function mintPublicUserJwt(auth: {
524
- space: string;
525
- account: Pick<SpaceAccountAuth["account"], "pub" | "signingSeed">;
526
- }, publicId: string, profile: Profile, opts: MintOpts): Promise<{
527
- jwt: string;
528
- exp: number;
529
- }>;
530
- /** Host-only service-callout mint. The host authenticates the connection and bearer, fixes
531
- * expiry before authority reads, and keeps this JWT inside its encrypted authorization response.
532
- * Native root reauthorization and natkey recording remain the host's final release obligations.
533
- */
534
- export declare function mintServiceCalloutJwt(auth: {
535
- space: string;
536
- account: Pick<SpaceAccountAuth["account"], "pub" | "signingSeed">;
537
- }, args: {
538
- serve: EpServeGrant;
539
- gate: EpIssuanceGate;
540
- principal: {
541
- owner: string;
542
- actor: string;
543
- };
544
- connection: ServiceConnectionBinding;
545
- inboxNonce: string;
546
- admittedAt: number;
547
- accessExpiresAt: number;
548
- expiresAt: number;
549
- }): Promise<{
550
- jwt: string;
551
- credentialId: string;
552
- iat: number;
553
- exp: number;
554
- }>;
555
- /** Build the NATS user permission object for a profile: a default-deny allow-list scoped to
556
- * exactly what each profile does. Every profile is now enumerated least-privilege — the former
557
- * allow-all `manager` is gone (its roles split across supervisor/provisioner/operator/purger and the
558
- * CLI-surface profiles). Subject/stream/durable names come from the shared builders so the ACLs
559
- * can't drift from the wire layout.
560
- *
561
- * PRINCIPAL-PARAMETERIZED + MODE-AGNOSTIC (owner+actor grammar): `pr` carries the owner+actor wire
562
- * principal (chat/inst/svc/ctl subjects, per-agent durables, the presence key all scope to it) PLUS the
563
- * connection nkey (`pr.connId`, which scopes the private reply inbox `_INBOX_<connId>`). Core does NOT
564
- * fork on dev-vs-user — the composition root supplies the principal: the auth callout passes the derived
565
- * owner + ledger actor + the per-connection ephemeral nkey; the static/dev mint passes
566
- * `{owner:"local", actor:<id>, connId:<id>}` via {@link principalOf}. EXPORTED so the callout's injected
567
- * `permissionsFor` hook can feed a validated principal straight into the same builder. */
568
- export declare function permissionsFor(profile: Profile, space: string, pr: MintPrincipal, opts: MintOpts): Record<string, unknown>;
569
- /** The rows a listing generation adds to a legacy-rail credential (SPEC 13.15, "Listing
570
- * issuance"): the registry's `endpoints` request publish and its reply subscribe on `ep.v1`, and
571
- * the per-key read of the generation's accepted row. Exactly these: one caller value emits one
572
- * rail, so these are the only `ep.v1` rows such a credential holds. */
573
- export declare function listingGrantRows(space: string, caller: EpCaller, listing: ListingBinding): {
574
- pub: string[];
575
- sub: string[];
576
- };
577
- /** Mint the scoped `membership-observer` creds — a SYSTEM-account user (conn A of the graph feed),
578
- * signed with the in-memory `auth.sys.signingSeed` from a fresh {@link createSpaceAuth}. THROWS if that
579
- * seed is absent (a re-`up` of an already-provisioned space, whose `$SYS` seed was discarded at its
580
- * original `up`): the observer can only be minted at the (re-)provision that creates the account — a
581
- * documented migration property, not a silent no-op. The CONNZ/event subjects pin the DATA account id
582
- * (`auth.account.pub`). Mirrors {@link mintCreds} but issues into the system account. */
583
- export declare function mintMembershipObserverCreds(auth: SpaceAuth, identity: Identity, opts?: MintOpts): Promise<string>;
584
- /** Host-only read-only census credential. A registered system signer is required; no fallback
585
- * to a broader observer or eviction credential. Reissuing with a retained registered signer
586
- * needs no broker restart. The helper does not discover or persist that signer.
587
- */
588
- export declare function mintAccountCensusCreds(auth: {
589
- account: {
590
- pub: string;
591
- };
592
- sys: {
593
- pub: string;
594
- signingSeed?: string;
595
- };
596
- }, identity: Identity, opts?: MintOpts): Promise<string>;
597
- /** Mint the scoped `connection-evictor` creds — the kick-only SYSTEM-account user for live
598
- * eviction. Same mint-only-at-provision property as the observer (the $SYS seed is in-memory
599
- * only), same fail-loud when it's absent. Paired with the observer at `up`. */
600
- export declare function mintConnectionEvictorCreds(auth: SpaceAuth, identity: Identity, opts?: MintOpts): Promise<string>;
601
1
  /**
602
- * Render the config for an OPEN (no-auth) broker.
2
+ * The provisioner — the signer capability for a space.
603
3
  *
604
- * This exists so that no path reaches a listener without naming its transport. Open mode used to
605
- * start nats-server from bare CLI flags (`-js -sd … -p … -a …`) and never called `serverConfig` at
606
- * all, which meant the required `transport` union protected the auth path and was silent on the
607
- * open one: an operator could pass a cert and key, watch `up` print its normal banner, and get a
608
- * cleartext listener. That is the silent downgrade this feature exists to prevent, reachable by
609
- * someone who did everything right — so open mode renders a config too.
4
+ * A space is one NATS *account*; every agent is a *user* in it. This module mints the
5
+ * decentralized-JWT trust chain (operator → account → user) programmatically with
6
+ * `@nats-io/jwt`, so there is no dependency on the external `nsc` CLI and the signing
7
+ * key stays in one place (whoever holds {@link SpaceAuth.account.signingSeed}).
610
8
  *
611
- * It deliberately does NOT reuse `serverConfig`: that renders the operator, system account and
612
- * MEMORY resolver, none of which a no-auth broker should carry. What the two share is the thing
613
- * that matters — a REQUIRED transport, so the choice cannot be omitted on either path.
9
+ * The static mint is out of band: `cotal up` creates the space's trust material
10
+ * once and writes a `nats-server` config (operator + system account + MEMORY resolver);
11
+ * `cotal mint` and the manager load that material and mint per-agent creds files. The auth
12
+ * callout mints at connect time through the same {@link permissionsFor}.
614
13
  *
615
- * IMPORTANT, and it must be said wherever open-mode TLS is surfaced to an operator: TLS ON AN
616
- * OPEN MESH GIVES CONFIDENTIALITY, NOT AUTHENTICATION. It hides traffic from a passive observer.
617
- * It does not verify who is connecting, because an open broker has no credentials to check — so
618
- * anyone who can reach the port still gets in, encrypted. It is a legitimate configuration for a
619
- * mesh crossing a network nobody controls, and it is NOT "secure" in the sense a reader will
620
- * assume from seeing `cotals://`. Describe it as the caveat it is rather than as a feature.
14
+ * Every credential kind is classified in {@link CREDENTIAL_LIFETIMES}: its lifetime class, default
15
+ * expiry and renewal owner.
621
16
  */
622
- export declare function openServerConfig(opts: {
623
- port?: number;
624
- host?: string;
625
- storeDir: string;
626
- /** Version of the broker this configuration targets. Enables version-specific JetStream limits. */
627
- brokerVersion?: string;
628
- /** JetStream file storage cap in bytes (`max_file_store`). Omitted leaves nats-server's dynamic
629
- * default. nats-server fixes the cap at start and refuses a reload that changes it. */
630
- maxFileStore?: number;
631
- /** Native broker message size limit in bytes. Omitted leaves nats-server's default. */
632
- maxPayload?: number;
633
- /** Native nats-server file logging and rotation. Rotation bounds require {@link logFile}. */
634
- logFile?: string;
635
- logfileSizeLimit?: number;
636
- logfileMaxNum?: number;
637
- transport: BrokerTransport;
638
- }): string;
639
- /** The exact `jetstream{}` block both broker renderers write for this store and cap, for a caller
640
- * that must find or replace it in a rendered configuration. */
641
- export declare function brokerJetStreamBlock(storeDir: string, maxFileStore?: number, brokerVersion?: string): string;
642
- /** How the broker resolves account JWTs. `memory`, the default, is the static preload map, so adding
643
- * or removing an account rewrites the whole config and reloads the broker. `full` is nats-server's
644
- * directory resolver: it keeps each account's operator-signed claim in `directory` (at most `limit`
645
- * of them, synchronized every `intervalMs`) and takes new or updated claims at run time from
646
- * {@link pushAccountClaim}, with no reload. Native deletion stays off; {@link retireAccountClaim}
647
- * stops an account instead. nats-server refuses to switch resolvers on a reload, so moving a broker
648
- * between the two is a restart. */
649
- export type AccountResolver = {
650
- kind: "memory";
651
- } | {
652
- kind: "full";
653
- directory: string;
654
- limit: number;
655
- intervalMs: number;
656
- };
657
- /** Render the `nats-server` config that trusts ONE broker operator and serves N spaces' accounts,
658
- * resolved by MEMORY unless {@link AccountResolver} `full` is chosen.
659
- *
660
- * Broker trust (operator + system account) comes from `broker` and has exactly one owner; the
661
- * per-space data accounts are listed in `spaces`. Every space account is asserted to be signed by
662
- * THIS broker's operator before it is preloaded: rendering a foreign-signed account would either
663
- * refuse broker boot or, worse, advertise a tenant the broker cannot actually authenticate.
664
- *
665
- * NOTE: the MEMORY resolver is one static whole-broker map, so every mutation rewrites all of
666
- * it. With the `full` resolver the preloads seed its directory at boot, and nats-server keeps a
667
- * newer pushed claim over an older preload, so a later render does not undo a push. Concurrent
668
- * add/remove of spaces needs a broker-authoritative inventory with generation/CAS and atomic
669
- * promotion above this function; this renderer is deliberately pure. */
670
- export declare function serverConfig(broker: BrokerAuth, spaces: readonly SpaceAccountAuth[], opts: {
671
- port?: number;
672
- host?: string;
673
- storeDir: string;
674
- /** Version of the broker this configuration targets. Enables version-specific JetStream limits. */
675
- brokerVersion?: string;
676
- /** JetStream file storage cap in bytes (`max_file_store`). Omitted leaves nats-server's dynamic
677
- * default. nats-server fixes the cap at start and refuses a reload that changes it. */
678
- maxFileStore?: number;
679
- /** Native nats-server file logging and rotation. Rotation bounds require {@link logFile}. */
680
- logFile?: string;
681
- logfileSizeLimit?: number;
682
- logfileMaxNum?: number;
683
- /** Explicit broker-wide payload limit. Omitted preserves nats-server's default. */
684
- maxPayload?: number;
685
- /** How long nats-server waits for an auth callout's answer, in whole seconds, rendered as
686
- * `authorization { timeout: N }`. Omitted renders no block and leaves nats-server's default. An
687
- * auth callout serving this broker must use the same value as its deadline. */
688
- authTimeout?: number;
689
- /** Account resolution; omitted is MEMORY, byte-identical to `{ kind: "memory" }`. */
690
- accountResolver?: AccountResolver;
691
- /** Additional operator-signed accounts to preload in the resolver — e.g. the dedicated
692
- * auth-callout account (`@cotal-ai/auth`), which must never share the data account. */
693
- extraAccounts?: Array<{
694
- pub: string;
695
- jwt: string;
696
- }>;
697
- /** How the client port is served. REQUIRED, and required on purpose: an optional TLS field
698
- * would let any future path that regenerates this config omit it and silently render a
699
- * plaintext listener. Callers must say `{ kind: "plaintext" }` when that is what they mean.
700
- * TLS is listener-wide, so it lives here in the broker options rather than per space —
701
- * no space can enable, disable or rotate it independently. */
702
- transport: BrokerTransport;
703
- /** OPT-IN NATS websocket listener port: browsers cannot speak raw NATS TCP, so the
704
- * console session client (a real mesh caller) needs one. This is a NEW ATTACK SURFACE the broker
705
- * did not have — emitted only when set, DEFAULT-BOUND TO LOCALHOST ({@link wsHost}), no TLS
706
- * (dev loopback; a remote/TLS dashboard is a later explicit opt-in). Omit it and no listener
707
- * exists (a broker with no console need adds no surface). */
708
- wsPort?: number;
709
- /** Bind host for the websocket listener; defaults to loopback. Widening it (a remote dashboard)
710
- * is a deliberate operator choice, never the default. */
711
- wsHost?: string;
712
- }): string;
17
+ export { capabilityRole, taskRoles, permissionsFor, listingGrantRows } from "./provision-permissions.js";
18
+ export type { Profile } from "./provision-permissions.js";
19
+ export { MAX_CONTROL_LINE_BYTES, CONNECT_ENVELOPE_OVERHEAD_BYTES, MAX_MINTED_JWT_BYTES, STANDING_RENEWABLE_TTL_SEC, ROTATION_RENEWED_TTL_SEC, CREDENTIAL_LIFETIMES, credentialLifetime, inspectCredHealth, composeSpaceAuth, assertAccountSignedByBroker, stripSpaceAuth, accountRevocations, revokeAccountUser, retireAccountClaim, rotateSystemAccount, createBrokerAuth, createSpaceAccountAuth, createSpaceAuth, mintCreds, mintPublicUserJwt, mintServiceCalloutJwt, mintMembershipObserverCreds, mintAccountCensusCreds, mintConnectionEvictorCreds } from "./provision-jwt.js";
20
+ export type { CredentialLifetimeClass, CredentialKind, CredentialLifetimePolicy, CredHealthState, CredHealth, BrokerAuth, SpaceAccountAuth, SpaceAuth, IssuedBinding, MintOpts, MintPrincipal } from "./provision-jwt.js";
21
+ export { provisionAgent, provisionAgentDurables } from "./provision-resources.js";
22
+ export type { ProvisionOpts, DurableProvisioner } from "./provision-resources.js";
23
+ export { openServerConfig, brokerJetStreamBlock, serverConfig } from "./provision-server-config.js";
24
+ export type { AccountResolver } from "./provision-server-config.js";
713
25
  //# sourceMappingURL=provision.d.ts.map