@cotal-ai/core 0.167.0 → 0.168.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.
- package/dist/endpoint-call.d.ts +4 -2
- package/dist/endpoint-call.d.ts.map +1 -1
- package/dist/endpoint-call.js +16 -7
- package/dist/endpoint-call.js.map +1 -1
- package/dist/endpoint-provenance.d.ts +11 -0
- package/dist/endpoint-provenance.d.ts.map +1 -0
- package/dist/endpoint-provenance.js +20 -0
- package/dist/endpoint-provenance.js.map +1 -0
- package/dist/endpoint-serve.d.ts.map +1 -1
- package/dist/endpoint-serve.js +1 -9
- package/dist/endpoint-serve.js.map +1 -1
- package/dist/endpoint.d.ts +19 -2
- package/dist/endpoint.d.ts.map +1 -1
- package/dist/endpoint.js +76 -17
- package/dist/endpoint.js.map +1 -1
- package/dist/provision-jwt.d.ts +518 -0
- package/dist/provision-jwt.d.ts.map +1 -0
- package/dist/provision-jwt.js +641 -0
- package/dist/provision-jwt.js.map +1 -0
- package/dist/provision-permissions.d.ts +72 -0
- package/dist/provision-permissions.d.ts.map +1 -0
- package/dist/provision-permissions.js +2009 -0
- package/dist/provision-permissions.js.map +1 -0
- package/dist/provision-resources.d.ts +66 -0
- package/dist/provision-resources.d.ts.map +1 -0
- package/dist/provision-resources.js +61 -0
- package/dist/provision-resources.js.map +1 -0
- package/dist/provision-server-config.d.ts +115 -0
- package/dist/provision-server-config.d.ts.map +1 -0
- package/dist/provision-server-config.js +169 -0
- package/dist/provision-server-config.js.map +1 -0
- package/dist/provision.d.ts +19 -707
- package/dist/provision.d.ts.map +1 -1
- package/dist/provision.js +4 -2860
- package/dist/provision.js.map +1 -1
- package/package.json +1 -1
package/dist/provision.d.ts
CHANGED
|
@@ -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
|
-
*
|
|
2
|
+
* The provisioner — the signer capability for a space.
|
|
603
3
|
*
|
|
604
|
-
*
|
|
605
|
-
*
|
|
606
|
-
*
|
|
607
|
-
*
|
|
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
|
-
*
|
|
612
|
-
*
|
|
613
|
-
*
|
|
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
|
-
*
|
|
616
|
-
*
|
|
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
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
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
|