@mnmal-ai/substrate 0.0.0-stage → 1.0.0-alpha.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/LICENSE +202 -0
- package/README.md +119 -2
- package/dist/agent-token-BIboWOU0.js +200 -0
- package/dist/client.d.ts +782 -0
- package/dist/client.js +7 -0
- package/dist/cluster-worker.js +35 -0
- package/dist/content-type-C7T28xNb.js +25 -0
- package/dist/dataset-BXkus75W.js +1527 -0
- package/dist/env-utils-B7SGmoeJ.js +21 -0
- package/dist/errors-D4vKuwz8.d.ts +130 -0
- package/dist/fake-DUVtKVSE.js +36 -0
- package/dist/index-D7mSOFlM.d.ts +69 -0
- package/dist/pack.d.ts +192 -0
- package/dist/pack.js +5 -0
- package/dist/plugin-j1jt1l3n.js +3844 -0
- package/dist/plugin-t2g2wX0b.d.ts +1568 -0
- package/dist/proposals-bootstrap.js +37 -0
- package/dist/proposals.config.schema.json +20 -0
- package/dist/proposals.d.ts +118 -0
- package/dist/proposals.default-config.json +4 -0
- package/dist/proposals.js +4 -0
- package/dist/recall-bootstrap.js +451 -0
- package/dist/recall.config.schema.json +232 -0
- package/dist/recall.d.ts +1981 -0
- package/dist/recall.default-config.json +4 -0
- package/dist/recall.js +5 -0
- package/dist/repl-C52wyfMs.js +2213 -0
- package/dist/row-ByLFE2Wx.d.ts +719 -0
- package/dist/row-DK7lPZVe.js +732 -0
- package/dist/runtime-metrics-DwpDJ8vz.d.ts +159 -0
- package/dist/schema-g4FQLr0V.d.ts +433 -0
- package/dist/sdk.d.ts +694 -0
- package/dist/sdk.js +112 -0
- package/dist/src-C4DzaIQZ.js +837 -0
- package/dist/src-CrEgiMJQ.js +1015 -0
- package/dist/src-CzxvmhFn.js +2327 -0
- package/dist/src-D88LvCX8.js +1797 -0
- package/dist/src-D91yij6C.js +13523 -0
- package/dist/src-DuopV8u7.js +2408 -0
- package/dist/substrate-admin.js +808 -0
- package/dist/substrate.js +5477 -0
- package/dist/testing.d.ts +1240 -0
- package/dist/testing.js +702 -0
- package/dist/types-8c0gtnd2.d.ts +35 -0
- package/dist/ws-C72iVS5T.d.ts +143 -0
- package/package.json +117 -3
|
@@ -0,0 +1,719 @@
|
|
|
1
|
+
import { E as Row, s as FieldInput } from "./schema-g4FQLr0V.js";
|
|
2
|
+
import { l as BridgeCredential } from "./runtime-metrics-DwpDJ8vz.js";
|
|
3
|
+
import { J as AutoCrudVerb, Q as PolicyDecision, Z as Policy, et as RequestContext } from "./plugin-t2g2wX0b.js";
|
|
4
|
+
//#region ../../packages/substrate-types/src/nl.d.ts
|
|
5
|
+
/**
|
|
6
|
+
* The engine-dispatchable frame a successful NL translation produces. Keys
|
|
7
|
+
* are qualified (`<ns>/<TypeName>` or `<ns>/<mutationName>`) so the caller can
|
|
8
|
+
* pass it straight to `engine.query({ frame })`.
|
|
9
|
+
*/
|
|
10
|
+
type Query = Record<string, {
|
|
11
|
+
params?: Record<string, unknown>;
|
|
12
|
+
fields: FieldInput;
|
|
13
|
+
}>;
|
|
14
|
+
/**
|
|
15
|
+
* In-context exemplar the NL agent embeds in the system prompt. Pairs the raw
|
|
16
|
+
* user prompt with the target Query for few-shot grounding.
|
|
17
|
+
*/
|
|
18
|
+
interface NLBase {
|
|
19
|
+
prompt: string;
|
|
20
|
+
query: Query;
|
|
21
|
+
explanation?: string;
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* The shape returned by `NLQueryAgent.translate`. `rawOutput` is the provider's
|
|
25
|
+
* verbatim text (used for debugging + `_nl` diagnostics on the route response).
|
|
26
|
+
*/
|
|
27
|
+
interface NLResult {
|
|
28
|
+
query: Query;
|
|
29
|
+
rawOutput: string;
|
|
30
|
+
explanation?: string;
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Optional vocabulary hint block — maps a user-visible term (`"mellow"`) to a
|
|
34
|
+
* concrete field/operator/value triple. The prompt builder renders it, but the
|
|
35
|
+
* `POST /substrate/v1/nl` body does not expose it.
|
|
36
|
+
*/
|
|
37
|
+
interface NLVocabularyHint {
|
|
38
|
+
term: string;
|
|
39
|
+
field: string;
|
|
40
|
+
operator: string;
|
|
41
|
+
value: unknown;
|
|
42
|
+
notes?: string;
|
|
43
|
+
}
|
|
44
|
+
//#endregion
|
|
45
|
+
//#region ../../packages/substrate-types/src/nl-wire.d.ts
|
|
46
|
+
interface NlAskRequest {
|
|
47
|
+
namespace: string;
|
|
48
|
+
question: string;
|
|
49
|
+
project?: string;
|
|
50
|
+
/** Force the reading to this type; resubmit a clarify option's `type`. Must name a type of the namespace. */
|
|
51
|
+
type?: string;
|
|
52
|
+
}
|
|
53
|
+
type NlParseStatus = 'resolved' | 'ambiguous' | 'partial' | 'clarify' | 'refuse' | 'unparsed';
|
|
54
|
+
interface NlEvidence {
|
|
55
|
+
span: string;
|
|
56
|
+
role: 'id' | 'type' | 'value' | 'time' | 'order' | 'count' | 'scope' | 'field' | 'author' | 'history';
|
|
57
|
+
detail: string;
|
|
58
|
+
}
|
|
59
|
+
type NlJudgeAction = 'pick' | 'type' | 'bind' | 'recall' | 'clarify' | 'refuse' | 'escalate';
|
|
60
|
+
interface NlJudgeChoice {
|
|
61
|
+
action: NlJudgeAction;
|
|
62
|
+
candidate?: number;
|
|
63
|
+
type?: string;
|
|
64
|
+
word?: string;
|
|
65
|
+
/** `Type.field`. */
|
|
66
|
+
field?: string;
|
|
67
|
+
op?: 'eq' | 'startsWith' | 'contains';
|
|
68
|
+
}
|
|
69
|
+
interface NlJudgeStep {
|
|
70
|
+
parse: {
|
|
71
|
+
status: NlParseStatus;
|
|
72
|
+
reason?: string;
|
|
73
|
+
};
|
|
74
|
+
choice?: NlJudgeChoice;
|
|
75
|
+
/** Why the reply was not applied. */
|
|
76
|
+
rejected?: string;
|
|
77
|
+
}
|
|
78
|
+
/** What an ask answered. The four kinds are exhaustive. */
|
|
79
|
+
type NlOutcome = {
|
|
80
|
+
kind: 'rows';
|
|
81
|
+
frame: Query;
|
|
82
|
+
answer: string;
|
|
83
|
+
/** Absent on the wire when the engine rejected the frame; `errors` then says why. */
|
|
84
|
+
data: unknown;
|
|
85
|
+
errors?: unknown[];
|
|
86
|
+
source: 'parser' | 'judge' | 'handoff';
|
|
87
|
+
handoff?: string;
|
|
88
|
+
} | {
|
|
89
|
+
kind: 'recall';
|
|
90
|
+
query: string;
|
|
91
|
+
/** Absent on the wire when the engine rejected the frame. */
|
|
92
|
+
hits: unknown[] | undefined;
|
|
93
|
+
errors?: unknown[];
|
|
94
|
+
} | {
|
|
95
|
+
kind: 'clarify';
|
|
96
|
+
question: string;
|
|
97
|
+
reason: string;
|
|
98
|
+
options: {
|
|
99
|
+
label: string;
|
|
100
|
+
question: string;
|
|
101
|
+
type: string;
|
|
102
|
+
}[];
|
|
103
|
+
} | {
|
|
104
|
+
kind: 'refuse';
|
|
105
|
+
reason: string;
|
|
106
|
+
};
|
|
107
|
+
interface NlParsedData {
|
|
108
|
+
status: NlParseStatus;
|
|
109
|
+
frame?: Query;
|
|
110
|
+
evidence: NlEvidence[];
|
|
111
|
+
residual: string[];
|
|
112
|
+
reason?: string;
|
|
113
|
+
}
|
|
114
|
+
type NlJudgedStatus = 'resolved' | 'recall' | 'clarify' | 'refuse' | 'escalated';
|
|
115
|
+
/**
|
|
116
|
+
* One SSE event, discriminated by the SSE event name. The terminal answer is
|
|
117
|
+
* named by its outcome kind (`rows` | `recall` | `clarify` | `refuse`) and
|
|
118
|
+
* carries the whole outcome; `done` always follows. An in-band `error` event
|
|
119
|
+
* is not in this union: the client throws on it.
|
|
120
|
+
*/
|
|
121
|
+
type NlWireEvent = {
|
|
122
|
+
event: 'parsed';
|
|
123
|
+
data: NlParsedData;
|
|
124
|
+
} | {
|
|
125
|
+
event: 'judging';
|
|
126
|
+
data: {
|
|
127
|
+
reason: string;
|
|
128
|
+
};
|
|
129
|
+
} | {
|
|
130
|
+
event: 'judged';
|
|
131
|
+
data: {
|
|
132
|
+
status: NlJudgedStatus;
|
|
133
|
+
trail: NlJudgeStep[];
|
|
134
|
+
};
|
|
135
|
+
} | {
|
|
136
|
+
event: 'rows';
|
|
137
|
+
data: Extract<NlOutcome, {
|
|
138
|
+
kind: 'rows';
|
|
139
|
+
}>;
|
|
140
|
+
} | {
|
|
141
|
+
event: 'recall';
|
|
142
|
+
data: Extract<NlOutcome, {
|
|
143
|
+
kind: 'recall';
|
|
144
|
+
}>;
|
|
145
|
+
} | {
|
|
146
|
+
event: 'clarify';
|
|
147
|
+
data: Extract<NlOutcome, {
|
|
148
|
+
kind: 'clarify';
|
|
149
|
+
}>;
|
|
150
|
+
} | {
|
|
151
|
+
event: 'refuse';
|
|
152
|
+
data: Extract<NlOutcome, {
|
|
153
|
+
kind: 'refuse';
|
|
154
|
+
}>;
|
|
155
|
+
} | {
|
|
156
|
+
event: 'done';
|
|
157
|
+
data: Record<string, never>;
|
|
158
|
+
};
|
|
159
|
+
/**
|
|
160
|
+
* The JSON encoding's trail spells the terminal event `outcome`, where SSE
|
|
161
|
+
* names it by the outcome kind.
|
|
162
|
+
*/
|
|
163
|
+
type NlTrailEvent = ({
|
|
164
|
+
event: 'parsed';
|
|
165
|
+
} & NlParsedData) | {
|
|
166
|
+
event: 'judging';
|
|
167
|
+
reason: string;
|
|
168
|
+
} | {
|
|
169
|
+
event: 'judged';
|
|
170
|
+
status: NlJudgedStatus;
|
|
171
|
+
trail: NlJudgeStep[];
|
|
172
|
+
} | {
|
|
173
|
+
event: 'outcome';
|
|
174
|
+
outcome: NlOutcome;
|
|
175
|
+
} | {
|
|
176
|
+
event: 'done';
|
|
177
|
+
};
|
|
178
|
+
/** The JSON encoding of `POST /substrate/v1/nl`. `outcome` is null only when the run was aborted. */
|
|
179
|
+
interface NlAskResult {
|
|
180
|
+
outcome: NlOutcome | null;
|
|
181
|
+
trail: NlTrailEvent[];
|
|
182
|
+
}
|
|
183
|
+
interface NlPackField {
|
|
184
|
+
name: string;
|
|
185
|
+
/** `metadata` marks a server-managed virtual (createdAt, createdById, ...). */
|
|
186
|
+
kind: 'scalar' | 'crossRef' | 'list' | 'struct' | 'metadata';
|
|
187
|
+
valueType?: string;
|
|
188
|
+
/** crossRef target type. */
|
|
189
|
+
target?: string;
|
|
190
|
+
indexed: boolean;
|
|
191
|
+
operators: string[];
|
|
192
|
+
phrases: string[];
|
|
193
|
+
enum?: string[];
|
|
194
|
+
/** Vocabulary aliases from the schema (alias -> canonical). The server applies them. */
|
|
195
|
+
aliases?: Record<string, string>;
|
|
196
|
+
/** Distinct values in the profile when the field is vocabulary. */
|
|
197
|
+
distinct?: number;
|
|
198
|
+
}
|
|
199
|
+
interface NlPackType {
|
|
200
|
+
name: string;
|
|
201
|
+
/** Lower-case phrases that name the type: singular, plural, head noun. */
|
|
202
|
+
phrases: string[];
|
|
203
|
+
fields: Record<string, NlPackField>;
|
|
204
|
+
}
|
|
205
|
+
interface NlPackValueRef {
|
|
206
|
+
type: string;
|
|
207
|
+
field: string;
|
|
208
|
+
/** The value as stored, original casing. */
|
|
209
|
+
value: string;
|
|
210
|
+
}
|
|
211
|
+
interface NlNamespacePack {
|
|
212
|
+
namespace: string;
|
|
213
|
+
schemaVersion: string;
|
|
214
|
+
types: Record<string, NlPackType>;
|
|
215
|
+
/** Lower-cased value -> every (type, field) it occurs in, sorted. */
|
|
216
|
+
values: Record<string, NlPackValueRef[]>;
|
|
217
|
+
}
|
|
218
|
+
interface NlValueAlias {
|
|
219
|
+
type: string;
|
|
220
|
+
field: string;
|
|
221
|
+
/** Exactly one of these. */
|
|
222
|
+
in?: string[];
|
|
223
|
+
eq?: string;
|
|
224
|
+
startsWith?: string;
|
|
225
|
+
contains?: string;
|
|
226
|
+
}
|
|
227
|
+
interface NlNamespaceRulings {
|
|
228
|
+
/** Types never scoped to the asking project (their `project` means "belongs to", not "applies to"). */
|
|
229
|
+
unscopedTypes?: string[];
|
|
230
|
+
/** Extra phrases naming a type, e.g. `backlog` -> Task. Win over the generated phrases. */
|
|
231
|
+
typeAliases?: Record<string, string>;
|
|
232
|
+
/** Extra phrases naming a field, e.g. `repo` -> project. */
|
|
233
|
+
fieldAliases?: Record<string, string>;
|
|
234
|
+
/**
|
|
235
|
+
* The status value that means "live" for a type, e.g. `Task` -> `open`
|
|
236
|
+
* ("the tasks" are the open ones). A list question about
|
|
237
|
+
* the type defaults to it, and a bare live word ("what's open") picks the
|
|
238
|
+
* types it is the live state of. Types not named here get no default.
|
|
239
|
+
*/
|
|
240
|
+
liveStatus?: Record<string, string>;
|
|
241
|
+
/**
|
|
242
|
+
* The date a type is "when" by, where it is not `createdAt`: a Meeting
|
|
243
|
+
* happened at `startedAt`, whenever its row was written. A field named in
|
|
244
|
+
* the question, or a closing/updating verb, still wins.
|
|
245
|
+
*/
|
|
246
|
+
timeField?: Record<string, string>;
|
|
247
|
+
/** What a type records, in a phrase. Shown to the judge only; the parser never reads it. */
|
|
248
|
+
typeNotes?: Record<string, string>;
|
|
249
|
+
/** A phrase that means a predicate, e.g. `accepted` -> Decision.status in [active, accepted]. */
|
|
250
|
+
valueAliases?: Record<string, NlValueAlias[]>;
|
|
251
|
+
}
|
|
252
|
+
/** The body of `GET /substrate/v1/nl/pack/:ns`. */
|
|
253
|
+
interface NlServedPack extends NlNamespacePack {
|
|
254
|
+
rulings: NlNamespaceRulings;
|
|
255
|
+
warnings: string[];
|
|
256
|
+
}
|
|
257
|
+
//#endregion
|
|
258
|
+
//#region ../../packages/substrate-policy/src/admin-credential.d.ts
|
|
259
|
+
/** The admin-identity env both `substrate-admin` and substrate-tui read. */
|
|
260
|
+
interface AdminEnv {
|
|
261
|
+
SUBSTRATE_ADMIN_TOKEN?: string;
|
|
262
|
+
SUBSTRATE_ADMIN_KEY_PATH?: string;
|
|
263
|
+
SUBSTRATE_ADMIN_KEY_ID?: string;
|
|
264
|
+
/** The capability that means admin; default `admin`. Read by the diagnosers, not the resolver. */
|
|
265
|
+
SUBSTRATE_ADMIN_CAPABILITY?: string;
|
|
266
|
+
HOME?: string;
|
|
267
|
+
}
|
|
268
|
+
/** Where the admin identity is: a ready bearer, a key to sign with, or why neither. */
|
|
269
|
+
type AdminCredential = {
|
|
270
|
+
readonly kind: 'token';
|
|
271
|
+
readonly authorization: string;
|
|
272
|
+
} | {
|
|
273
|
+
readonly kind: 'key';
|
|
274
|
+
readonly keyPath: string;
|
|
275
|
+
readonly kid: string;
|
|
276
|
+
} | {
|
|
277
|
+
readonly kind: 'error';
|
|
278
|
+
readonly error: string;
|
|
279
|
+
};
|
|
280
|
+
/**
|
|
281
|
+
* Where `bootstrap` writes the admin private key, and where
|
|
282
|
+
* {@link resolveAdminCredential} looks for it.
|
|
283
|
+
*/
|
|
284
|
+
declare function resolveDefaultKeyPath(env: AdminEnv): string;
|
|
285
|
+
/** Companion to {@link resolveDefaultKeyPath}, for the kid file. */
|
|
286
|
+
declare function resolveDefaultKidPath(env: AdminEnv): string;
|
|
287
|
+
/**
|
|
288
|
+
* Locate the admin credential, or explain what to set. Signing is the caller's
|
|
289
|
+
* job: it may need a passphrase for the key first.
|
|
290
|
+
*
|
|
291
|
+
* Fail-loud: a message naming the missing key is more use than the 401 an
|
|
292
|
+
* unauthenticated admin call would get.
|
|
293
|
+
*/
|
|
294
|
+
declare function resolveAdminCredential(env: AdminEnv): AdminCredential;
|
|
295
|
+
//#endregion
|
|
296
|
+
//#region ../../packages/substrate-policy/src/admin-key.d.ts
|
|
297
|
+
/** The kernel namespace holding Key, Invite and the admin routes' rows. */
|
|
298
|
+
declare const SYSTEM_NAMESPACE = "_system";
|
|
299
|
+
/**
|
|
300
|
+
* Does this row count as an ACTIVE ADMIN key? True when unrevoked, with a kid,
|
|
301
|
+
* and its grant confers `adminCapability` in `_system` (explicit entry, else the
|
|
302
|
+
* wildcard) — the same question `requireCapability` asks at dispatch, through
|
|
303
|
+
* the same parser. Admin scoped to another namespace (e.g. `tasks`) does not
|
|
304
|
+
* count.
|
|
305
|
+
*/
|
|
306
|
+
declare function isActiveAdminKeyRow(row: Row, adminCapability: string): boolean;
|
|
307
|
+
/**
|
|
308
|
+
* The grant, one line per namespace, in the SAME syntax `--ns` accepts.
|
|
309
|
+
*
|
|
310
|
+
* `tasks:read+mutate` round-trips: paste a rendered line back into `--ns` and
|
|
311
|
+
* it means what it says here.
|
|
312
|
+
*
|
|
313
|
+
* TOTAL, and it has to be: this runs inside a formatter, after the write has
|
|
314
|
+
* already committed. `parseGrantEntries` throws on a malformed entry, and a
|
|
315
|
+
* throw here would lose the operator the record of an operation that SUCCEEDED.
|
|
316
|
+
* An unparseable grant falls back to naming the raw columns and saying so.
|
|
317
|
+
*/
|
|
318
|
+
declare function describeGrant(namespaces: string, capabilities: string): string[];
|
|
319
|
+
//#endregion
|
|
320
|
+
//#region ../../packages/substrate-policy/src/agent-token.d.ts
|
|
321
|
+
/**
|
|
322
|
+
* What a token claims when the caller says nothing. Least privilege: `admin` is
|
|
323
|
+
* opt-in, never a default. Exported so consumers name it rather than copy it.
|
|
324
|
+
*/
|
|
325
|
+
declare const DEFAULT_CAPABILITIES: ReadonlyArray<string>;
|
|
326
|
+
/**
|
|
327
|
+
* What an ADMIN caller should claim.
|
|
328
|
+
*
|
|
329
|
+
* The claim is narrowed by the registry row it is checked against
|
|
330
|
+
* (`substrate-compose/src/auth.ts`, via `intersectGrants(claim, row)`), so
|
|
331
|
+
* claiming a superset is safe — the row is the authority and the token only
|
|
332
|
+
* asks. What is NOT safe is claiming a SUBSET: anything the row grants and the
|
|
333
|
+
* claim omits is intersected away. That is the whole defect this constant
|
|
334
|
+
* exists for, so it lists every capability an admin row might carry rather than
|
|
335
|
+
* `admin` alone. A capability the ROW does not grant stays unreachable; no
|
|
336
|
+
* claim fixes that.
|
|
337
|
+
*
|
|
338
|
+
* Deliberately an enumeration, not `['*']`: the capability gates (`withAuth`,
|
|
339
|
+
* `requireCapability`) do a bare membership test with no wildcard case, so a
|
|
340
|
+
* `'*'` claim is refused everything. `substrate-compose`'s
|
|
341
|
+
* `agent-token-capability-intersection` suite pins this list against the
|
|
342
|
+
* `Capability` union.
|
|
343
|
+
*/
|
|
344
|
+
declare const ADMIN_CAPABILITIES: ReadonlyArray<string>;
|
|
345
|
+
/**
|
|
346
|
+
* What an admin flow CLAIMS on a deployment: {@link ADMIN_CAPABILITIES} plus
|
|
347
|
+
* `SUBSTRATE_ADMIN_CAPABILITY` when that names something else.
|
|
348
|
+
*
|
|
349
|
+
* A deployment whose admin capability is not `admin` seeds its admin row with
|
|
350
|
+
* that name, so a claim of {@link ADMIN_CAPABILITIES} alone intersects it away
|
|
351
|
+
* and the admin gate answers no. Unset or empty means the default, as every
|
|
352
|
+
* other reader of the variable treats it.
|
|
353
|
+
*/
|
|
354
|
+
declare function adminClaimCapabilities(env: {
|
|
355
|
+
SUBSTRATE_ADMIN_CAPABILITY?: string;
|
|
356
|
+
}): ReadonlyArray<string>;
|
|
357
|
+
interface TokenProviderOpts {
|
|
358
|
+
/**
|
|
359
|
+
* Defer reading and parsing the key to the first mint instead of doing it at
|
|
360
|
+
* construction.
|
|
361
|
+
*
|
|
362
|
+
* For callers constructed inside an event handler or a discovery callback,
|
|
363
|
+
* where a throw becomes an unhandled rejection rather than a startup failure
|
|
364
|
+
* a supervisor can see.
|
|
365
|
+
*/
|
|
366
|
+
lazyKey?: boolean;
|
|
367
|
+
/**
|
|
368
|
+
* Capabilities to CLAIM. Defaults to `['read', 'mutate']`.
|
|
369
|
+
*
|
|
370
|
+
* A dataset-backed key's registry row narrows this by intersection, so the
|
|
371
|
+
* claim is a request and the row is the authority — a token can never widen
|
|
372
|
+
* itself. The hazard runs the other way: a claim that omits what the row
|
|
373
|
+
* grants intersects it AWAY: an `admin` identity claiming only the default
|
|
374
|
+
* ends up with no capabilities. Pass {@link adminClaimCapabilities} for admin flows.
|
|
375
|
+
*/
|
|
376
|
+
capabilities?: ReadonlyArray<string>;
|
|
377
|
+
/** Namespaces to CLAIM. Defaults to `['*']`. Narrowed by the row the same way. */
|
|
378
|
+
namespaces?: ReadonlyArray<string>;
|
|
379
|
+
/**
|
|
380
|
+
* Passphrase for an encrypted PKCS#8 PEM (`substrate-admin bootstrap --encrypt`). Without it an
|
|
381
|
+
* encrypted key cannot be read at all. Held only inside the provider.
|
|
382
|
+
*/
|
|
383
|
+
passphrase?: string;
|
|
384
|
+
/** The `aud` claim: the origin the token is minted for. Omitted when unset. */
|
|
385
|
+
audience?: string;
|
|
386
|
+
}
|
|
387
|
+
/**
|
|
388
|
+
* Returns a provider yielding the BARE JWT. Re-signs once the cached token is
|
|
389
|
+
* within {@link REFRESH_SKEW} of expiry.
|
|
390
|
+
*
|
|
391
|
+
* Bare, not `Bearer <jwt>`: the prefix is a transport concern. Callers that
|
|
392
|
+
* want the header value use {@link makeAuthorizationProvider}.
|
|
393
|
+
*
|
|
394
|
+
* Throws at construction on an unreadable or malformed key unless
|
|
395
|
+
* {@link TokenProviderOpts.lazyKey} is set. Signing itself stays lazy either
|
|
396
|
+
* way — only the read moves.
|
|
397
|
+
*
|
|
398
|
+
* Takes only the signing half of a {@link BridgeCredential}: `origin` binds a
|
|
399
|
+
* credential to a destination, which is the caller's gate to enforce before it
|
|
400
|
+
* ever reaches a signer, and the MCP env wrapper has no origin to supply.
|
|
401
|
+
*/
|
|
402
|
+
declare function makeTokenProvider(cred: Pick<BridgeCredential, 'keyPath' | 'kid'>, opts?: TokenProviderOpts): () => string;
|
|
403
|
+
/** Is the PEM at `keyPath` an encrypted PKCS#8 key, which needs a passphrase to read? */
|
|
404
|
+
declare function isEncryptedKey(keyPath: string): boolean;
|
|
405
|
+
/**
|
|
406
|
+
* Returns a provider yielding the full `Authorization` header value,
|
|
407
|
+
* `Bearer <jwt>`, over {@link makeTokenProvider}.
|
|
408
|
+
*
|
|
409
|
+
* Keeps the `Bearer ` literal in one place.
|
|
410
|
+
*/
|
|
411
|
+
declare function makeAuthorizationProvider(cred: Pick<BridgeCredential, 'keyPath' | 'kid'>, opts?: TokenProviderOpts): () => string;
|
|
412
|
+
//#endregion
|
|
413
|
+
//#region ../../packages/substrate-policy/src/combinators.d.ts
|
|
414
|
+
/**
|
|
415
|
+
* AND combinator. Allow iff every policy allows; short-circuits on first deny.
|
|
416
|
+
* Empty `and()` is the identity element and returns allow (per §4.4).
|
|
417
|
+
*/
|
|
418
|
+
declare function and(...policies: Policy[]): Policy;
|
|
419
|
+
/**
|
|
420
|
+
* OR combinator. Allow iff any policy allows; short-circuits on first allow.
|
|
421
|
+
* When all deny, the LAST deny's reason is returned — EXCEPT a caught
|
|
422
|
+
* `'policy error'` from any position always wins over sibling deny reasons
|
|
423
|
+
* (invariant #2).
|
|
424
|
+
*/
|
|
425
|
+
declare function or(...policies: Policy[]): Policy;
|
|
426
|
+
/**
|
|
427
|
+
* NOT combinator. Inverts allow/deny, EXCEPT caught errors propagate through
|
|
428
|
+
* unchanged (invariant #2). Preserves the inner decision's `reason` on the
|
|
429
|
+
* returned deny so callers can see it; omits `reason` entirely when the inner
|
|
430
|
+
* allow had no reason (invariant #5).
|
|
431
|
+
*/
|
|
432
|
+
declare function not(p: Policy): Policy;
|
|
433
|
+
//#endregion
|
|
434
|
+
//#region ../../packages/substrate-policy/src/encoding.d.ts
|
|
435
|
+
/**
|
|
436
|
+
* Comma-separated string-list encoding. Spec §5.12.
|
|
437
|
+
*
|
|
438
|
+
* The `_system` namespace stores `Key.namespaces`, `Key.capabilities`,
|
|
439
|
+
* `Invite.namespaces`, and `Invite.capabilities` as comma-separated
|
|
440
|
+
* scalar strings rather than list-typed fields. The two helpers below are the
|
|
441
|
+
* only allowed encode/decode path — use sites must NOT hand-roll `.split(',')`
|
|
442
|
+
* because the empty-input → `[]` rule lives here.
|
|
443
|
+
*/
|
|
444
|
+
/**
|
|
445
|
+
* Canonicalise a string array for persistence. Trims each entry, rejects
|
|
446
|
+
* embedded commas (no quoting in the substrate column), and joins with `,`.
|
|
447
|
+
* Empty input returns `''` — keeping the column non-null and trivially
|
|
448
|
+
* round-trippable through `decodeList`.
|
|
449
|
+
*/
|
|
450
|
+
declare function encodeList(items: Array<string>): string;
|
|
451
|
+
/**
|
|
452
|
+
* Inverse of `encodeList`. Accepts the stored scalar (possibly `''` for an
|
|
453
|
+
* empty list), splits on `,`, trims, drops empties. Non-string inputs — the
|
|
454
|
+
* dataset shouldn't emit these, but defence-in-depth — yield `[]`.
|
|
455
|
+
*/
|
|
456
|
+
declare function decodeList(raw: unknown): Array<string>;
|
|
457
|
+
//#endregion
|
|
458
|
+
//#region ../../packages/substrate-policy/src/grant.d.ts
|
|
459
|
+
/**
|
|
460
|
+
* Per-namespace capability grants (spec §5): a namespace → capabilities map.
|
|
461
|
+
*
|
|
462
|
+
* A flat `(namespaces × capabilities)` grant must expand and intersect exactly
|
|
463
|
+
* as the two independent list intersections did, since stored keys are flat;
|
|
464
|
+
* `test/_system/grant.test.ts` asserts that equivalence.
|
|
465
|
+
*
|
|
466
|
+
* Stored in the comma-separated `Key.namespaces` column as entries like
|
|
467
|
+
* `notes:read` or `tasks:read+mutate`. `+` separates capabilities because `,`
|
|
468
|
+
* is taken by the column and `:` by the namespace separator.
|
|
469
|
+
*/
|
|
470
|
+
/** A namespace → capabilities map. `'*'` is a legal key: the wildcard grant. */
|
|
471
|
+
type Grant = ReadonlyMap<string, ReadonlySet<string>>;
|
|
472
|
+
/**
|
|
473
|
+
* The capabilities this grant confers in `ns`.
|
|
474
|
+
*
|
|
475
|
+
* An EXPLICIT entry beats the wildcard, which is what makes
|
|
476
|
+
* `--ns '*:read,tasks:read+mutate'` mean the obvious thing — read everywhere,
|
|
477
|
+
* and also write tasks — rather than being ambiguous about which entry wins.
|
|
478
|
+
*/
|
|
479
|
+
declare function capabilitiesFor(grant: Grant, ns: string): ReadonlySet<string>;
|
|
480
|
+
/** The flat form, expanded. This is the cross product, stated as a map. */
|
|
481
|
+
declare function expandFlat(namespaces: readonly string[], capabilities: readonly string[]): Grant;
|
|
482
|
+
/**
|
|
483
|
+
* Parses the CLI/route entry list. An entry without `:` takes
|
|
484
|
+
* `defaultCapabilities`, so a bare `--ns notes` keeps its flat meaning.
|
|
485
|
+
*
|
|
486
|
+
* @throws Error naming the entry when one has an empty namespace or no
|
|
487
|
+
* capabilities.
|
|
488
|
+
*/
|
|
489
|
+
declare function parseGrantEntries(entries: readonly string[], defaultCapabilities: readonly string[]): Grant;
|
|
490
|
+
/**
|
|
491
|
+
* The reason this entry list will not parse, or `null` when it will.
|
|
492
|
+
*
|
|
493
|
+
* Validates by calling {@link parseGrantEntries} so the rules cannot drift
|
|
494
|
+
* from the parser. The message is the parser's own and carries no fix
|
|
495
|
+
* instruction; each caller appends its own vocabulary.
|
|
496
|
+
*/
|
|
497
|
+
declare function grantEntryError(entries: readonly string[], defaultCapabilities: readonly string[]): string | null;
|
|
498
|
+
/**
|
|
499
|
+
* Back to entry form for storage. An entry whose capabilities equal
|
|
500
|
+
* `defaultCapabilities` emits BARE, so a flat grant round-trips to the exact
|
|
501
|
+
* csv it came from and an operator reading `substrate-admin list` sees no new
|
|
502
|
+
* syntax until someone actually uses it.
|
|
503
|
+
*/
|
|
504
|
+
declare function encodeGrant(grant: Grant, defaultCapabilities: readonly string[]): string[];
|
|
505
|
+
/**
|
|
506
|
+
* Claim ∩ row, per namespace.
|
|
507
|
+
*
|
|
508
|
+
* A wildcard claim (`ns: ['*']`, what agent tokens send) yields the row's
|
|
509
|
+
* grant, via `capabilitiesFor` resolving `'*'` for every namespace the row
|
|
510
|
+
* names.
|
|
511
|
+
*/
|
|
512
|
+
declare function intersectGrants(claim: Grant, row: Grant): Grant;
|
|
513
|
+
/**
|
|
514
|
+
* The flat compatibility view.
|
|
515
|
+
*
|
|
516
|
+
* `namespaces` is every namespace held at ANY level (§8.1) and
|
|
517
|
+
* `capabilities` is the UNION — which is what `withAuth`'s any-namespace
|
|
518
|
+
* pre-check needs. It is deliberately NOT the answer to "what am I granted";
|
|
519
|
+
* `grant` is. Consumers that render this to a human must consult
|
|
520
|
+
* {@link grantIsUniform} first.
|
|
521
|
+
*/
|
|
522
|
+
declare function flattenGrant(grant: Grant): {
|
|
523
|
+
namespaces: string[];
|
|
524
|
+
capabilities: string[];
|
|
525
|
+
};
|
|
526
|
+
/**
|
|
527
|
+
* Does every namespace in this grant carry the same capabilities?
|
|
528
|
+
*
|
|
529
|
+
* When false, no single flat capability list is honest, and §8.1 renders
|
|
530
|
+
* `null` rather than picking one.
|
|
531
|
+
*/
|
|
532
|
+
declare function grantIsUniform(grant: Grant): boolean;
|
|
533
|
+
//#endregion
|
|
534
|
+
//#region ../../packages/substrate-policy/src/key-guards.d.ts
|
|
535
|
+
/**
|
|
536
|
+
* Shared refusal rules for mutating a `_system/Key`, used by both the
|
|
537
|
+
* `substrate-admin` CLI and the key routes so the lockout guard cannot drift.
|
|
538
|
+
*
|
|
539
|
+
* The READ is deliberately not shared: the CLI reads inside its own
|
|
540
|
+
* `withTransaction`; the route reads through `engine.query` so the registry
|
|
541
|
+
* interceptor fires. Each caller gathers the facts and hands them here.
|
|
542
|
+
*
|
|
543
|
+
* Refusals are RETURNED, not thrown. The CLI maps them to its exit codes and
|
|
544
|
+
* the route maps them to HTTP statuses; a shared thrower would force one
|
|
545
|
+
* caller's error vocabulary onto the other.
|
|
546
|
+
*/
|
|
547
|
+
/** Why a key mutation is refused. `null` from a check means "allowed". */
|
|
548
|
+
type KeyMutationRefusal = {
|
|
549
|
+
code: 'unknown_kid';
|
|
550
|
+
message: string;
|
|
551
|
+
} | {
|
|
552
|
+
code: 'already_revoked';
|
|
553
|
+
message: string;
|
|
554
|
+
revokedAt: string;
|
|
555
|
+
} | {
|
|
556
|
+
code: 'last_active_admin';
|
|
557
|
+
message: string;
|
|
558
|
+
};
|
|
559
|
+
/** Normalise a `revokedAt` cell to an ISO string, or null when the key is live. */
|
|
560
|
+
declare function revokedAtIso(value: unknown): string | null;
|
|
561
|
+
/**
|
|
562
|
+
* The revoke verdict.
|
|
563
|
+
*
|
|
564
|
+
* `activeAdminKids` is every kid that {@link isActiveAdminKeyRow} accepts,
|
|
565
|
+
* gathered by the caller. Passing an INCOMPLETE list silently weakens the
|
|
566
|
+
* lockout guard, so callers must read the whole key table, never a page of it.
|
|
567
|
+
*/
|
|
568
|
+
declare function checkRevocable(input: {
|
|
569
|
+
kid: string;
|
|
570
|
+
/** The row's `revokedAt`, or `null` when live. Pass `undefined` for "no such row". */
|
|
571
|
+
existingRevokedAt: unknown | undefined;
|
|
572
|
+
exists: boolean;
|
|
573
|
+
activeAdminKids: ReadonlyArray<string>;
|
|
574
|
+
}): KeyMutationRefusal | null;
|
|
575
|
+
/** Does `granted` already cover `item`? A `*` grant covers everything. */
|
|
576
|
+
declare function grantCovers(granted: ReadonlyArray<string>, item: string): boolean;
|
|
577
|
+
/**
|
|
578
|
+
* Entries in `next` that `prev` did not already grant.
|
|
579
|
+
*
|
|
580
|
+
* This — not "is the new set a strict superset" — is the test that matters. A
|
|
581
|
+
* lateral change like `tasks` -> `notes` is neither a superset nor a subset,
|
|
582
|
+
* yet it hands the key an authority it did not hold. Empty result means the
|
|
583
|
+
* change grants nothing new, i.e. it narrows, and narrowing needs no flag.
|
|
584
|
+
*/
|
|
585
|
+
declare function newlyGranted(prev: ReadonlyArray<string>, next: ReadonlyArray<string>): Array<string>;
|
|
586
|
+
/**
|
|
587
|
+
* Entries in `next` that `prev` did not already grant, as `(ns, cap)` PAIRS
|
|
588
|
+
* (spec §6). A wildcard entry in `prev` covers any namespace at the
|
|
589
|
+
* capabilities it conferred. A pure narrowing yields the empty set.
|
|
590
|
+
*
|
|
591
|
+
* Returns entries GROUPED BY NAMESPACE in the CLI's own spelling —
|
|
592
|
+
* `recall:read+mutate`, not `recall:read, recall:mutate` — for the operator-
|
|
593
|
+
* facing refusal message.
|
|
594
|
+
*/
|
|
595
|
+
declare function newlyGrantedPairs(prev: Readonly<Record<string, ReadonlyArray<string>>>, next: Readonly<Record<string, ReadonlyArray<string>>>): Array<string>;
|
|
596
|
+
/**
|
|
597
|
+
* Does this entry list confer `capability` in any namespace?
|
|
598
|
+
*
|
|
599
|
+
* The shared predicate behind the `--allow-admin` / `allowAdmin` opt-in, so
|
|
600
|
+
* `register` (CLI and route) and `update` cannot answer it differently. Reads
|
|
601
|
+
* the parsed grant, not the flat list, so `--ns '_system:admin' --caps read`
|
|
602
|
+
* still trips it.
|
|
603
|
+
*
|
|
604
|
+
* Returns `true` on an unparseable list: this is a confirmation gate, so the
|
|
605
|
+
* safe failure is asking for confirmation, never handing a privilege over
|
|
606
|
+
* unasked.
|
|
607
|
+
*/
|
|
608
|
+
declare function grantEntriesConfer(entries: ReadonlyArray<string>, defaultCapabilities: ReadonlyArray<string>, capability: string): boolean;
|
|
609
|
+
/** Why an in-place key update is refused. `null` means allowed. */
|
|
610
|
+
type KeyUpdateRefusal = KeyMutationRefusal | {
|
|
611
|
+
code: 'last_admin_deadmin';
|
|
612
|
+
message: string;
|
|
613
|
+
} | {
|
|
614
|
+
code: 'requires_widen';
|
|
615
|
+
message: string;
|
|
616
|
+
namespacesGranted: Array<string>;
|
|
617
|
+
capabilitiesGranted: Array<string>;
|
|
618
|
+
} | {
|
|
619
|
+
code: 'requires_allow_admin';
|
|
620
|
+
message: string;
|
|
621
|
+
} | {
|
|
622
|
+
code: 'invalid_grant';
|
|
623
|
+
message: string;
|
|
624
|
+
};
|
|
625
|
+
/**
|
|
626
|
+
* The in-place update verdict. Returns the first refusal, or `null` if allowed.
|
|
627
|
+
*
|
|
628
|
+
* ORDER IS PART OF THE RULE: **unconditional refusals outrank confirmable
|
|
629
|
+
* ones.** One request can trip both the lockout and the widen gate; reporting
|
|
630
|
+
* the confirmable one first sends the operator to add the flag, re-run, and
|
|
631
|
+
* dead-end on the lockout.
|
|
632
|
+
*/
|
|
633
|
+
declare function checkUpdatable(input: {
|
|
634
|
+
kid: string;
|
|
635
|
+
exists: boolean;
|
|
636
|
+
existingRevokedAt: unknown | undefined;
|
|
637
|
+
prevNamespaces: ReadonlyArray<string>;
|
|
638
|
+
prevCapabilities: ReadonlyArray<string>;
|
|
639
|
+
nextNamespaces: ReadonlyArray<string>;
|
|
640
|
+
nextCapabilities: ReadonlyArray<string>;
|
|
641
|
+
/** Every kid that {@link isActiveAdminKeyRow} accepts. Must be the WHOLE set. */
|
|
642
|
+
activeAdminKids: ReadonlyArray<string>;
|
|
643
|
+
adminCapability: string;
|
|
644
|
+
widen: boolean;
|
|
645
|
+
allowAdmin: boolean;
|
|
646
|
+
}): KeyUpdateRefusal | null;
|
|
647
|
+
//#endregion
|
|
648
|
+
//#region ../../packages/substrate-policy/src/primitives.d.ts
|
|
649
|
+
/**
|
|
650
|
+
* Always allows. Useful as an explicit identity element for `and(...)` and as a
|
|
651
|
+
* default for resolvers that have no access constraints.
|
|
652
|
+
*/
|
|
653
|
+
declare function allowAll(): Policy;
|
|
654
|
+
/**
|
|
655
|
+
* Always denies. Reason defaults to `'denyAll'` when none is supplied so the
|
|
656
|
+
* caller surface always has something to log.
|
|
657
|
+
*/
|
|
658
|
+
declare function denyAll(reason?: string): Policy;
|
|
659
|
+
/**
|
|
660
|
+
* Allow when the request has a verified identity attached. The most common
|
|
661
|
+
* minimum bar for authenticated resolvers; composes with role / rate / row
|
|
662
|
+
* policies via `and(...)`.
|
|
663
|
+
*/
|
|
664
|
+
declare function requireIdentity(): Policy;
|
|
665
|
+
/**
|
|
666
|
+
* Allow when the identity carries the named capability in its
|
|
667
|
+
* `capabilities: string[]` claim. Admin gates on `purge<T>` and other
|
|
668
|
+
* sensitive mutations compose with this. Per §5.12, the capability name
|
|
669
|
+
* comes from `SUBSTRATE_ADMIN_CAPABILITY` (default `'admin'`).
|
|
670
|
+
*
|
|
671
|
+
* Rejects both when no identity is attached and when identity lacks the
|
|
672
|
+
* capability — callers don't need to stack `requireIdentity()` first.
|
|
673
|
+
*/
|
|
674
|
+
declare function requireCapability(name: string): Policy;
|
|
675
|
+
/**
|
|
676
|
+
* Allow when the identity's grant covers `ns` — explicit entry or wildcard.
|
|
677
|
+
* Resolved through `grantOf`, the same function the engine gate uses, so the
|
|
678
|
+
* two cannot disagree.
|
|
679
|
+
*
|
|
680
|
+
* Rejects when no identity is attached or when the grant does not cover `ns`;
|
|
681
|
+
* composes with `requireCapability` via `and` for resolver policies that need
|
|
682
|
+
* both a capability and a namespace grant.
|
|
683
|
+
*/
|
|
684
|
+
declare function requireNamespace(ns: string): Policy;
|
|
685
|
+
/**
|
|
686
|
+
* Deny dispatches whose autoCRUD verb is in `verbs`; allow everything else.
|
|
687
|
+
* Keys on `ctx.verb` — the semantic verb the engine threads from
|
|
688
|
+
* the registry entry — so the intent survives entry renames. Entries WITHOUT
|
|
689
|
+
* a verb (type entries, custom mutations) are allowed by this primitive;
|
|
690
|
+
* gate those by `ctx.entry` name or compose additional policies.
|
|
691
|
+
*
|
|
692
|
+
* `purge<T>` is stamped `verb: 'delete'` by autoCRUD, so `denyVerbs(['delete'])`
|
|
693
|
+
* covers both soft- and hard-delete surfaces.
|
|
694
|
+
*/
|
|
695
|
+
declare function denyVerbs(verbs: ReadonlyArray<AutoCrudVerb>, reason?: string): Policy;
|
|
696
|
+
/**
|
|
697
|
+
* Allow ONLY dispatches whose autoCRUD verb is in `verbs`.
|
|
698
|
+
* Stricter complement of `denyVerbs`: entries WITHOUT a verb (type entries,
|
|
699
|
+
* custom mutations) are DENIED — an allow-list should not silently pass
|
|
700
|
+
* surfaces it cannot classify. Compose with `or(...)` if reads-via-type-entry
|
|
701
|
+
* must also pass: `or(allowVerbs(['get']), <type-entry policy>)`.
|
|
702
|
+
*/
|
|
703
|
+
declare function allowVerbs(verbs: ReadonlyArray<AutoCrudVerb>, reason?: string): Policy;
|
|
704
|
+
//#endregion
|
|
705
|
+
//#region ../../packages/substrate-policy/src/row.d.ts
|
|
706
|
+
/**
|
|
707
|
+
* Build a collection-time allow decision carrying a single row-filter
|
|
708
|
+
* obligation. Composes with `and`/`or` like any other policy.
|
|
709
|
+
*/
|
|
710
|
+
declare function row<T>(predicate: (ctx: RequestContext, row: T) => boolean): Policy;
|
|
711
|
+
/**
|
|
712
|
+
* Apply every row-filter obligation on `decision` to `rows`, in insertion
|
|
713
|
+
* order. Per §4.4, row-scoped denies are silent — returning false OR throwing
|
|
714
|
+
* drops the row without surfacing a reason. A decision without obligations
|
|
715
|
+
* returns `rows` unchanged.
|
|
716
|
+
*/
|
|
717
|
+
declare function applyRowFilters<T>(decision: PolicyDecision, rows: T[], ctx: RequestContext): T[];
|
|
718
|
+
//#endregion
|
|
719
|
+
export { NlJudgeStep as $, and as A, SYSTEM_NAMESPACE as B, flattenGrant as C, parseGrantEntries as D, intersectGrants as E, TokenProviderOpts as F, resolveAdminCredential as G, isActiveAdminKeyRow as H, adminClaimCapabilities as I, NlAskRequest as J, resolveDefaultKeyPath as K, isEncryptedKey as L, or as M, ADMIN_CAPABILITIES as N, decodeList as O, DEFAULT_CAPABILITIES as P, NlJudgeChoice as Q, makeAuthorizationProvider as R, expandFlat as S, grantIsUniform as T, AdminCredential as U, describeGrant as V, AdminEnv as W, NlEvidence as X, NlAskResult as Y, NlJudgeAction as Z, newlyGrantedPairs as _, denyAll as a, NlPackType as at, capabilitiesFor as b, requireIdentity as c, NlParsedData as ct, KeyUpdateRefusal as d, NlValueAlias as dt, NlJudgedStatus as et, checkRevocable as f, NlWireEvent as ft, newlyGranted as g, Query as gt, grantEntriesConfer as h, NLVocabularyHint as ht, allowVerbs as i, NlPackField as it, not as j, encodeList as k, requireNamespace as l, NlServedPack as lt, grantCovers as m, NLResult as mt, row as n, NlNamespaceRulings as nt, denyVerbs as o, NlPackValueRef as ot, checkUpdatable as p, NLBase as pt, resolveDefaultKidPath as q, allowAll as r, NlOutcome as rt, requireCapability as s, NlParseStatus as st, applyRowFilters as t, NlNamespacePack as tt, KeyMutationRefusal as u, NlTrailEvent as ut, revokedAtIso as v, grantEntryError as w, encodeGrant as x, Grant as y, makeTokenProvider as z };
|