@mfdaves/okf-mcp 0.9.1 → 0.13.0-rc.1
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/CHANGELOG.md +100 -0
- package/README.md +452 -26
- package/bin/okf-mcp.js +6 -1
- package/okf/okf-mcp/distribution/reference-bundle.md +10 -3
- package/okf/okf-mcp/index.md +2 -1
- package/okf/okf-mcp/interfaces/http-authoring-api.md +11 -2
- package/okf/okf-mcp/interfaces/mcp-http.md +64 -0
- package/okf/okf-mcp/interfaces/mcp-tools.md +25 -6
- package/okf/okf-mcp/overview/okf-mcp.md +16 -6
- package/okf/okf-mcp/policies/authoring-safety.md +28 -5
- package/okf/okf-mcp/runtime/indexer.md +14 -1
- package/okf/okf-mcp/runtime/mcp-server.md +16 -8
- package/okf/okf-mcp/specs/producer-api.md +16 -2
- package/package.json +17 -5
- package/server.json +38 -2
- package/src/assets.js +165 -73
- package/src/authoring/candidates.js +434 -0
- package/src/authoring/git-preflight.js +225 -0
- package/src/authoring/git-publish.js +783 -0
- package/src/authoring/live.js +757 -0
- package/src/authoring/paths.js +112 -0
- package/src/authoring/policy-hook.js +221 -0
- package/src/authoring/proposal-policy.js +159 -0
- package/src/authoring/receipts.js +373 -0
- package/src/authoring/render.js +38 -0
- package/src/authoring/shared.js +75 -0
- package/src/authoring/staging.js +216 -0
- package/src/authoring.js +386 -287
- package/src/cache/files.js +147 -0
- package/src/cache/lock.js +201 -0
- package/src/cache/paths.js +197 -0
- package/src/cache/store.js +703 -0
- package/src/catalog-text.js +19 -0
- package/src/cli/commands.js +448 -0
- package/src/cli/http-options.js +193 -0
- package/src/cli/options.js +554 -0
- package/src/cli/usage.js +96 -0
- package/src/cli.js +18 -932
- package/src/computation.js +99 -61
- package/src/context/assemble.js +567 -0
- package/src/context/cli-options.js +88 -0
- package/src/context/score.js +234 -0
- package/src/context/sections.js +274 -0
- package/src/embed/interface.js +160 -0
- package/src/embed/openai.js +715 -0
- package/src/embed/prepare.js +182 -0
- package/src/embed/units.js +96 -0
- package/src/error-details.js +53 -0
- package/src/git-source.js +112 -52
- package/src/graph.js +95 -37
- package/src/http-server.js +36 -17
- package/src/index.js +15 -0
- package/src/indexer/assemble.js +566 -0
- package/src/indexer/build.js +290 -0
- package/src/indexer/cache.js +81 -0
- package/src/indexer/edges.js +430 -0
- package/src/indexer/index.js +44 -0
- package/src/indexer/paths.js +178 -0
- package/src/indexer/resolve.js +282 -0
- package/src/indexer/update.js +720 -0
- package/src/indexer.js +3 -1068
- package/src/live-authoring.js +4 -2329
- package/src/markdown.js +21 -16
- package/src/mcp/auth.js +409 -0
- package/src/mcp/http.js +317 -0
- package/src/mcp/principal.js +59 -0
- package/src/mcp/registry.js +356 -0
- package/src/mcp/resources.js +45 -0
- package/src/mcp/server.js +567 -0
- package/src/mcp/tools/catalog.js +247 -0
- package/src/mcp/tools/computation.js +83 -0
- package/src/mcp/tools/context.js +133 -0
- package/src/mcp/tools/graph.js +167 -0
- package/src/mcp/tools/live-authoring.js +316 -0
- package/src/mcp/tools/migration.js +86 -0
- package/src/mcp/tools/producers.js +79 -0
- package/src/mcp/tools/proposals.js +225 -0
- package/src/mcp/tools/provenance.js +87 -0
- package/src/mcp/tools/remote.js +79 -0
- package/src/mcp/tools/search.js +242 -0
- package/src/mcp-server.js +3 -1611
- package/src/migration.js +431 -253
- package/src/parser.js +245 -130
- package/src/plugins.js +71 -48
- package/src/policy/write-policy.js +713 -0
- package/src/producer-publisher.js +202 -78
- package/src/producers.js +311 -103
- package/src/project.js +346 -93
- package/src/remote.js +96 -61
- package/src/search/cli-options.js +107 -0
- package/src/search/confidence.js +61 -0
- package/src/search/dense.js +304 -0
- package/src/search/embedding-cli.js +57 -0
- package/src/search/embedding-config.js +217 -0
- package/src/search/fusion.js +249 -0
- package/src/search/hybrid.js +526 -0
- package/src/search/languages.js +200 -0
- package/src/search/lexical.js +695 -0
- package/src/search/query.js +620 -0
- package/src/search/stem/among.js +43 -0
- package/src/search/stem/base-stemmer.js +311 -0
- package/src/search/stem/en-regions.js +456 -0
- package/src/search/stem/en-suffixes.js +664 -0
- package/src/search/stem/en-tables.js +176 -0
- package/src/search/stem/en.js +238 -0
- package/src/search/stem/it-regions.js +459 -0
- package/src/search/stem/it-suffixes.js +471 -0
- package/src/search/stem/it-tables.js +257 -0
- package/src/search/stem/it.js +155 -0
- package/src/search-index.js +2 -81
- package/src/search.js +2 -252
- package/src/store.js +134 -81
- package/src/tool-packs.js +346 -0
- package/src/v02.js +301 -105
- package/src/validation.js +24 -20
|
@@ -0,0 +1,713 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
const fs = require("node:fs");
|
|
4
|
+
const path = require("node:path");
|
|
5
|
+
|
|
6
|
+
const { realpathOfExistingAncestors } = require("../cache/paths");
|
|
7
|
+
const { resolveConcept } = require("../indexer/resolve");
|
|
8
|
+
const { normalizeSlashes, parseFrontmatterYaml } = require("../parser");
|
|
9
|
+
|
|
10
|
+
// Per-actor write policy (plan W-1). The policy is trusted configuration: it
|
|
11
|
+
// comes from okf.project.yaml or from --policy <file> in --root mode, never
|
|
12
|
+
// from a tool argument. It is evaluated against the changes of one batch
|
|
13
|
+
// only; existing content is never retro-validated.
|
|
14
|
+
|
|
15
|
+
const EFFECTS = new Set(["allow", "deny"]);
|
|
16
|
+
const STATUSES = new Set(["draft", "stable", "deprecated"]);
|
|
17
|
+
const POLICY_KEYS = new Set(["defaultEffect", "rules", "applyToProducers"]);
|
|
18
|
+
const RULE_KEYS = new Set([
|
|
19
|
+
"name",
|
|
20
|
+
"actors",
|
|
21
|
+
"bundles",
|
|
22
|
+
"paths",
|
|
23
|
+
"types",
|
|
24
|
+
"requiredFields",
|
|
25
|
+
"defaultStatus",
|
|
26
|
+
"maxConceptsPerBatch",
|
|
27
|
+
"effect",
|
|
28
|
+
]);
|
|
29
|
+
const ALLOW_ONLY_KEYS = ["requiredFields", "defaultStatus", "maxConceptsPerBatch"];
|
|
30
|
+
const MAX_RULES = 200;
|
|
31
|
+
const UNKNOWN_ACTOR = "unknown";
|
|
32
|
+
const MAX_PATTERN_LENGTH = 256;
|
|
33
|
+
const MAX_POLICY_FILE_BYTES = 256 * 1024;
|
|
34
|
+
const PARSED = Symbol.for("okf-mcp.write-policy.parsed");
|
|
35
|
+
|
|
36
|
+
function isPlainObject(value) {
|
|
37
|
+
if (!value || typeof value !== "object" || Array.isArray(value)) {
|
|
38
|
+
return false;
|
|
39
|
+
}
|
|
40
|
+
const prototype = Object.getPrototypeOf(value);
|
|
41
|
+
return prototype === Object.prototype || prototype === null;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
function hasOwn(value, key) {
|
|
45
|
+
return Boolean(value && Object.hasOwn(value, key));
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
function configError(code, field, message) {
|
|
49
|
+
return { code, field, message };
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
function hasControlCharacter(text) {
|
|
53
|
+
for (const character of text) {
|
|
54
|
+
const code = character.charCodeAt(0);
|
|
55
|
+
if (code < 0x20 || code === 0x7f) {
|
|
56
|
+
return true;
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
return false;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
// The glob subset: segments separated by "/"; a segment is "**" (any number
|
|
63
|
+
// of segments, including none), a literal, or a literal with "*" standing
|
|
64
|
+
// for any run of characters inside the segment. Nothing else is interpreted;
|
|
65
|
+
// a pattern never becomes a RegExp, so regex metacharacters are literal.
|
|
66
|
+
function compileGlobPattern(value, field, errors) {
|
|
67
|
+
const fail = (message) => {
|
|
68
|
+
errors.push(configError("invalid_write_policy_pattern", field, message));
|
|
69
|
+
return null;
|
|
70
|
+
};
|
|
71
|
+
if (typeof value !== "string" || !value.length) {
|
|
72
|
+
return fail("Pattern must be a non-empty string.");
|
|
73
|
+
}
|
|
74
|
+
if (value.length > MAX_PATTERN_LENGTH) {
|
|
75
|
+
return fail(`Pattern must not exceed ${MAX_PATTERN_LENGTH} characters.`);
|
|
76
|
+
}
|
|
77
|
+
if (hasControlCharacter(value)) {
|
|
78
|
+
return fail("Pattern cannot contain control characters.");
|
|
79
|
+
}
|
|
80
|
+
const normalized = normalizeSlashes(value);
|
|
81
|
+
if (normalized.startsWith("/") || /^[A-Za-z]:/.test(normalized)) {
|
|
82
|
+
return fail("Pattern must be relative; absolute paths are not allowed.");
|
|
83
|
+
}
|
|
84
|
+
const segments = normalized.split("/");
|
|
85
|
+
for (const segment of segments) {
|
|
86
|
+
if (segment === "") {
|
|
87
|
+
return fail("Pattern cannot contain empty segments.");
|
|
88
|
+
}
|
|
89
|
+
if (segment === "." || segment === "..") {
|
|
90
|
+
return fail("Pattern cannot contain . or .. segments.");
|
|
91
|
+
}
|
|
92
|
+
if (segment.includes("**") && segment !== "**") {
|
|
93
|
+
return fail("** must stand alone as a whole segment.");
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
return { source: value, segments };
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
// "*" inside one segment, matched by hand (no RegExp): the classic
|
|
100
|
+
// single-star wildcard walk with one backtrack point.
|
|
101
|
+
function matchSegment(pattern, text) {
|
|
102
|
+
let p = 0;
|
|
103
|
+
let t = 0;
|
|
104
|
+
let star = -1;
|
|
105
|
+
let mark = 0;
|
|
106
|
+
while (t < text.length) {
|
|
107
|
+
if (p < pattern.length && pattern[p] === "*") {
|
|
108
|
+
star = p;
|
|
109
|
+
mark = t;
|
|
110
|
+
p += 1;
|
|
111
|
+
} else if (p < pattern.length && pattern[p] === text[t]) {
|
|
112
|
+
p += 1;
|
|
113
|
+
t += 1;
|
|
114
|
+
} else if (star !== -1) {
|
|
115
|
+
p = star + 1;
|
|
116
|
+
mark += 1;
|
|
117
|
+
t = mark;
|
|
118
|
+
} else {
|
|
119
|
+
return false;
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
while (p < pattern.length && pattern[p] === "*") {
|
|
123
|
+
p += 1;
|
|
124
|
+
}
|
|
125
|
+
return p === pattern.length;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
function matchSegments(patterns, segments) {
|
|
129
|
+
const memo = new Map();
|
|
130
|
+
const go = (i, j) => {
|
|
131
|
+
if (i === patterns.length) {
|
|
132
|
+
return j === segments.length;
|
|
133
|
+
}
|
|
134
|
+
const key = i * (segments.length + 1) + j;
|
|
135
|
+
if (memo.has(key)) {
|
|
136
|
+
return memo.get(key);
|
|
137
|
+
}
|
|
138
|
+
let result;
|
|
139
|
+
if (patterns[i] === "**") {
|
|
140
|
+
result = go(i + 1, j) || (j < segments.length && go(i, j + 1));
|
|
141
|
+
} else {
|
|
142
|
+
result = j < segments.length && matchSegment(patterns[i], segments[j]) && go(i + 1, j + 1);
|
|
143
|
+
}
|
|
144
|
+
memo.set(key, result);
|
|
145
|
+
return result;
|
|
146
|
+
};
|
|
147
|
+
return go(0, 0);
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
function globMatch(pattern, value) {
|
|
151
|
+
if (!pattern || typeof value !== "string") {
|
|
152
|
+
return false;
|
|
153
|
+
}
|
|
154
|
+
return matchSegments(pattern.segments, normalizeSlashes(value).split("/"));
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
function matchesAny(patterns, value) {
|
|
158
|
+
return patterns.some((pattern) => globMatch(pattern, value));
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
function parsePatternList(value, field, errors) {
|
|
162
|
+
if (value === undefined) {
|
|
163
|
+
return null;
|
|
164
|
+
}
|
|
165
|
+
if (!Array.isArray(value) || !value.length) {
|
|
166
|
+
errors.push(configError("invalid_write_policy_rule", field, "Must be a non-empty array."));
|
|
167
|
+
return null;
|
|
168
|
+
}
|
|
169
|
+
const patterns = value.map((entry, index) =>
|
|
170
|
+
compileGlobPattern(entry, `${field}[${index}]`, errors),
|
|
171
|
+
);
|
|
172
|
+
return patterns.every(Boolean) ? patterns : null;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
function parseStringList(value, field, errors, validate) {
|
|
176
|
+
if (value === undefined) {
|
|
177
|
+
return null;
|
|
178
|
+
}
|
|
179
|
+
if (!Array.isArray(value) || !value.length) {
|
|
180
|
+
errors.push(configError("invalid_write_policy_rule", field, "Must be a non-empty array."));
|
|
181
|
+
return null;
|
|
182
|
+
}
|
|
183
|
+
let valid = true;
|
|
184
|
+
value.forEach((entry, index) => {
|
|
185
|
+
const message = validate(entry);
|
|
186
|
+
if (message) {
|
|
187
|
+
valid = false;
|
|
188
|
+
errors.push(configError("invalid_write_policy_rule", `${field}[${index}]`, message));
|
|
189
|
+
}
|
|
190
|
+
});
|
|
191
|
+
return valid ? value.slice() : null;
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
function nonBlankString(value) {
|
|
195
|
+
if (typeof value !== "string" || !value.trim() || hasControlCharacter(value)) {
|
|
196
|
+
return "Must be a non-empty string.";
|
|
197
|
+
}
|
|
198
|
+
return null;
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
function fieldName(value) {
|
|
202
|
+
if (typeof value !== "string" || !/^[A-Za-z0-9_][A-Za-z0-9_.:-]*$/.test(value)) {
|
|
203
|
+
return "Must be a frontmatter key: letters, numbers, underscores, dots, colons, or hyphens.";
|
|
204
|
+
}
|
|
205
|
+
return null;
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
function parseRule(raw, index, errors, names) {
|
|
209
|
+
const field = `writePolicy.rules[${index}]`;
|
|
210
|
+
if (!isPlainObject(raw)) {
|
|
211
|
+
errors.push(configError("invalid_write_policy_rule", field, "Rule must be an object."));
|
|
212
|
+
return null;
|
|
213
|
+
}
|
|
214
|
+
const before = errors.length;
|
|
215
|
+
Object.keys(raw)
|
|
216
|
+
.filter((key) => !RULE_KEYS.has(key))
|
|
217
|
+
.forEach((key) => {
|
|
218
|
+
errors.push(
|
|
219
|
+
configError(
|
|
220
|
+
"unknown_write_policy_field",
|
|
221
|
+
`${field}.${key}`,
|
|
222
|
+
`Unknown write policy rule field: ${key}`,
|
|
223
|
+
),
|
|
224
|
+
);
|
|
225
|
+
});
|
|
226
|
+
let name = null;
|
|
227
|
+
if (raw.name !== undefined) {
|
|
228
|
+
if (typeof raw.name !== "string" || !/^[A-Za-z0-9_.-]+$/.test(raw.name)) {
|
|
229
|
+
errors.push(
|
|
230
|
+
configError(
|
|
231
|
+
"invalid_write_policy_rule",
|
|
232
|
+
`${field}.name`,
|
|
233
|
+
"Rule name may contain only letters, numbers, underscores, dots, and hyphens.",
|
|
234
|
+
),
|
|
235
|
+
);
|
|
236
|
+
} else if (names.has(raw.name)) {
|
|
237
|
+
errors.push(
|
|
238
|
+
configError("invalid_write_policy_rule", `${field}.name`, "Rule names must be unique."),
|
|
239
|
+
);
|
|
240
|
+
} else {
|
|
241
|
+
names.add(raw.name);
|
|
242
|
+
name = raw.name;
|
|
243
|
+
}
|
|
244
|
+
}
|
|
245
|
+
const effect = raw.effect === undefined ? "allow" : raw.effect;
|
|
246
|
+
if (!EFFECTS.has(effect)) {
|
|
247
|
+
errors.push(
|
|
248
|
+
configError("invalid_write_policy_rule", `${field}.effect`, "effect must be allow or deny."),
|
|
249
|
+
);
|
|
250
|
+
}
|
|
251
|
+
if (raw.actors === undefined) {
|
|
252
|
+
errors.push(
|
|
253
|
+
configError("invalid_write_policy_rule", `${field}.actors`, "Rule requires actors."),
|
|
254
|
+
);
|
|
255
|
+
}
|
|
256
|
+
const actors = parsePatternList(raw.actors, `${field}.actors`, errors);
|
|
257
|
+
const bundles = parsePatternList(raw.bundles, `${field}.bundles`, errors);
|
|
258
|
+
const paths = parsePatternList(raw.paths, `${field}.paths`, errors);
|
|
259
|
+
const types = parseStringList(raw.types, `${field}.types`, errors, nonBlankString);
|
|
260
|
+
const requiredFields = parseStringList(
|
|
261
|
+
raw.requiredFields,
|
|
262
|
+
`${field}.requiredFields`,
|
|
263
|
+
errors,
|
|
264
|
+
fieldName,
|
|
265
|
+
);
|
|
266
|
+
let defaultStatus = null;
|
|
267
|
+
if (raw.defaultStatus !== undefined) {
|
|
268
|
+
if (!STATUSES.has(raw.defaultStatus)) {
|
|
269
|
+
errors.push(
|
|
270
|
+
configError(
|
|
271
|
+
"invalid_write_policy_rule",
|
|
272
|
+
`${field}.defaultStatus`,
|
|
273
|
+
"defaultStatus must be draft, stable, or deprecated.",
|
|
274
|
+
),
|
|
275
|
+
);
|
|
276
|
+
} else {
|
|
277
|
+
defaultStatus = raw.defaultStatus;
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
let maxConceptsPerBatch = null;
|
|
281
|
+
if (raw.maxConceptsPerBatch !== undefined) {
|
|
282
|
+
if (!Number.isInteger(raw.maxConceptsPerBatch) || raw.maxConceptsPerBatch < 1) {
|
|
283
|
+
errors.push(
|
|
284
|
+
configError(
|
|
285
|
+
"invalid_write_policy_rule",
|
|
286
|
+
`${field}.maxConceptsPerBatch`,
|
|
287
|
+
"maxConceptsPerBatch must be a positive integer.",
|
|
288
|
+
),
|
|
289
|
+
);
|
|
290
|
+
} else {
|
|
291
|
+
maxConceptsPerBatch = raw.maxConceptsPerBatch;
|
|
292
|
+
}
|
|
293
|
+
}
|
|
294
|
+
if (effect === "deny") {
|
|
295
|
+
ALLOW_ONLY_KEYS.filter((key) => raw[key] !== undefined).forEach((key) => {
|
|
296
|
+
errors.push(
|
|
297
|
+
configError(
|
|
298
|
+
"invalid_write_policy_rule",
|
|
299
|
+
`${field}.${key}`,
|
|
300
|
+
`${key} applies only to allow rules.`,
|
|
301
|
+
),
|
|
302
|
+
);
|
|
303
|
+
});
|
|
304
|
+
}
|
|
305
|
+
if (errors.length !== before) {
|
|
306
|
+
return null;
|
|
307
|
+
}
|
|
308
|
+
return {
|
|
309
|
+
id: name === null ? index : name,
|
|
310
|
+
index,
|
|
311
|
+
name,
|
|
312
|
+
effect,
|
|
313
|
+
actors,
|
|
314
|
+
bundles,
|
|
315
|
+
paths,
|
|
316
|
+
types: types ? new Set(types) : null,
|
|
317
|
+
requiredFields: requiredFields || [],
|
|
318
|
+
defaultStatus,
|
|
319
|
+
maxConceptsPerBatch,
|
|
320
|
+
};
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
// Parses the `writePolicy` mapping. Returns { policy, errors }: the policy is
|
|
324
|
+
// null when the input is absent (no policy) or invalid; errors carry a config
|
|
325
|
+
// field path like writePolicy.rules[1].paths[0], in the style of project.js.
|
|
326
|
+
function parseWritePolicy(raw) {
|
|
327
|
+
const errors = [];
|
|
328
|
+
if (raw === undefined || raw === null) {
|
|
329
|
+
return { policy: null, errors };
|
|
330
|
+
}
|
|
331
|
+
if (isWritePolicy(raw)) {
|
|
332
|
+
return { policy: raw, errors };
|
|
333
|
+
}
|
|
334
|
+
if (!isPlainObject(raw)) {
|
|
335
|
+
errors.push(
|
|
336
|
+
configError("invalid_write_policy", "writePolicy", "writePolicy must be an object."),
|
|
337
|
+
);
|
|
338
|
+
return { policy: null, errors };
|
|
339
|
+
}
|
|
340
|
+
Object.keys(raw)
|
|
341
|
+
.filter((key) => !POLICY_KEYS.has(key))
|
|
342
|
+
.forEach((key) => {
|
|
343
|
+
errors.push(
|
|
344
|
+
configError(
|
|
345
|
+
"unknown_write_policy_field",
|
|
346
|
+
`writePolicy.${key}`,
|
|
347
|
+
`Unknown write policy field: ${key}`,
|
|
348
|
+
),
|
|
349
|
+
);
|
|
350
|
+
});
|
|
351
|
+
const defaultEffect = raw.defaultEffect === undefined ? "allow" : raw.defaultEffect;
|
|
352
|
+
if (!EFFECTS.has(defaultEffect)) {
|
|
353
|
+
errors.push(
|
|
354
|
+
configError(
|
|
355
|
+
"invalid_write_policy",
|
|
356
|
+
"writePolicy.defaultEffect",
|
|
357
|
+
"defaultEffect must be allow or deny.",
|
|
358
|
+
),
|
|
359
|
+
);
|
|
360
|
+
}
|
|
361
|
+
// Producers publish under their own process:<name> actor and are exempt
|
|
362
|
+
// unless the operator opts them in.
|
|
363
|
+
const applyToProducers = raw.applyToProducers === undefined ? false : raw.applyToProducers;
|
|
364
|
+
if (typeof applyToProducers !== "boolean") {
|
|
365
|
+
errors.push(
|
|
366
|
+
configError(
|
|
367
|
+
"invalid_write_policy",
|
|
368
|
+
"writePolicy.applyToProducers",
|
|
369
|
+
"applyToProducers must be true or false.",
|
|
370
|
+
),
|
|
371
|
+
);
|
|
372
|
+
}
|
|
373
|
+
let rules = [];
|
|
374
|
+
if (raw.rules !== undefined) {
|
|
375
|
+
if (!Array.isArray(raw.rules)) {
|
|
376
|
+
errors.push(
|
|
377
|
+
configError("invalid_write_policy", "writePolicy.rules", "rules must be an array."),
|
|
378
|
+
);
|
|
379
|
+
} else if (raw.rules.length > MAX_RULES) {
|
|
380
|
+
errors.push(
|
|
381
|
+
configError(
|
|
382
|
+
"invalid_write_policy",
|
|
383
|
+
"writePolicy.rules",
|
|
384
|
+
`rules must not exceed ${MAX_RULES} entries.`,
|
|
385
|
+
),
|
|
386
|
+
);
|
|
387
|
+
} else {
|
|
388
|
+
const names = new Set();
|
|
389
|
+
rules = raw.rules.map((rule, index) => parseRule(rule, index, errors, names));
|
|
390
|
+
}
|
|
391
|
+
}
|
|
392
|
+
if (errors.length) {
|
|
393
|
+
return { policy: null, errors };
|
|
394
|
+
}
|
|
395
|
+
const policy = { defaultEffect, rules, applyToProducers };
|
|
396
|
+
Object.defineProperty(policy, PARSED, { value: true });
|
|
397
|
+
return { policy, errors };
|
|
398
|
+
}
|
|
399
|
+
|
|
400
|
+
function isWritePolicy(value) {
|
|
401
|
+
return Boolean(value && typeof value === "object" && value[PARSED] === true);
|
|
402
|
+
}
|
|
403
|
+
|
|
404
|
+
// A list counts as empty when every entry is: `sources: [""]` satisfies no
|
|
405
|
+
// requirement.
|
|
406
|
+
function isEmptyValue(value) {
|
|
407
|
+
if (value === undefined || value === null) return true;
|
|
408
|
+
if (typeof value === "string") return value.trim() === "";
|
|
409
|
+
if (Array.isArray(value)) return value.every(isEmptyValue);
|
|
410
|
+
if (isPlainObject(value)) return Object.keys(value).length === 0;
|
|
411
|
+
return false;
|
|
412
|
+
}
|
|
413
|
+
|
|
414
|
+
// One change as the evaluator sees it. Planned candidates carry everything;
|
|
415
|
+
// raw update changes may name only a uri, which the index resolves to the
|
|
416
|
+
// existing concept's bundle, path, type, and frontmatter.
|
|
417
|
+
function describeChange(change, position, index) {
|
|
418
|
+
if (!isPlainObject(change)) {
|
|
419
|
+
throw new TypeError(`changes[${position}] must be an object.`);
|
|
420
|
+
}
|
|
421
|
+
const described = {
|
|
422
|
+
op: change.op === "update" ? "update" : "create",
|
|
423
|
+
bundleId: change.bundleId || change.bundle || null,
|
|
424
|
+
path: typeof change.path === "string" ? normalizeSlashes(change.path) : null,
|
|
425
|
+
type: typeof change.type === "string" ? change.type : null,
|
|
426
|
+
frontmatter: isPlainObject(change.frontmatter) ? change.frontmatter : null,
|
|
427
|
+
uri: typeof change.uri === "string" ? change.uri : null,
|
|
428
|
+
};
|
|
429
|
+
if (index && described.uri && (described.path === null || described.type === null)) {
|
|
430
|
+
const existing = resolveConcept(index, described.uri);
|
|
431
|
+
if (existing?.valid && !existing.reserved) {
|
|
432
|
+
described.bundleId = described.bundleId || existing.bundle;
|
|
433
|
+
described.path = described.path || normalizeSlashes(existing.path);
|
|
434
|
+
described.type = described.type || existing.type || null;
|
|
435
|
+
described.frontmatter = described.frontmatter || existing.frontmatter || {};
|
|
436
|
+
described.uri = existing.uri;
|
|
437
|
+
}
|
|
438
|
+
}
|
|
439
|
+
described.frontmatter = described.frontmatter || {};
|
|
440
|
+
if (described.type === null && typeof described.frontmatter.type === "string") {
|
|
441
|
+
described.type = described.frontmatter.type;
|
|
442
|
+
}
|
|
443
|
+
return described;
|
|
444
|
+
}
|
|
445
|
+
|
|
446
|
+
// The first selector of a rule the change does not satisfy, in the order the
|
|
447
|
+
// selectors narrow a write: bundle, then path, then type. Absent selectors
|
|
448
|
+
// match everything; an unknown value never matches a present selector.
|
|
449
|
+
function failingSelector(rule, change) {
|
|
450
|
+
if (rule.bundles && !(change.bundleId && matchesAny(rule.bundles, change.bundleId))) {
|
|
451
|
+
return "bundle";
|
|
452
|
+
}
|
|
453
|
+
if (rule.paths && !(change.path && matchesAny(rule.paths, change.path))) {
|
|
454
|
+
return "path";
|
|
455
|
+
}
|
|
456
|
+
if (rule.types && !(change.type && rule.types.has(change.type))) {
|
|
457
|
+
return "type";
|
|
458
|
+
}
|
|
459
|
+
return null;
|
|
460
|
+
}
|
|
461
|
+
|
|
462
|
+
// Why a matching deny rule denies: named after its most specific selector.
|
|
463
|
+
function denyReason(rule) {
|
|
464
|
+
if (rule.paths) return "path_denied";
|
|
465
|
+
if (rule.types) return "type_denied";
|
|
466
|
+
if (rule.bundles) return "bundle_denied";
|
|
467
|
+
return "actor_denied";
|
|
468
|
+
}
|
|
469
|
+
|
|
470
|
+
function appliesDefaultStatus(rule, change) {
|
|
471
|
+
return Boolean(
|
|
472
|
+
rule.defaultStatus &&
|
|
473
|
+
change.op === "create" &&
|
|
474
|
+
(!hasOwn(change.frontmatter, "status") || isEmptyValue(change.frontmatter.status)),
|
|
475
|
+
);
|
|
476
|
+
}
|
|
477
|
+
|
|
478
|
+
// First rule whose actors match and whose other selectors (when present)
|
|
479
|
+
// match decides. Without a match the default effect applies; a default deny
|
|
480
|
+
// names the first actor-matching allow rule and the selector it failed, so
|
|
481
|
+
// the caller learns which rule nearly allowed the write.
|
|
482
|
+
function decide(policy, actor, change, input) {
|
|
483
|
+
let nearest = null;
|
|
484
|
+
let nearestFailure = null;
|
|
485
|
+
for (const rule of policy.rules) {
|
|
486
|
+
if (!matchesAny(rule.actors, actor)) continue;
|
|
487
|
+
const failure = failingSelector(rule, change);
|
|
488
|
+
if (failure) {
|
|
489
|
+
if (!nearest && rule.effect === "allow") {
|
|
490
|
+
nearest = rule;
|
|
491
|
+
nearestFailure = failure;
|
|
492
|
+
}
|
|
493
|
+
continue;
|
|
494
|
+
}
|
|
495
|
+
if (rule.effect === "deny") {
|
|
496
|
+
return { rule, id: rule.id, effect: "deny", reason: denyReason(rule), defaultStatus: null };
|
|
497
|
+
}
|
|
498
|
+
return {
|
|
499
|
+
rule,
|
|
500
|
+
id: rule.id,
|
|
501
|
+
effect: "allow",
|
|
502
|
+
reason: null,
|
|
503
|
+
defaultStatus:
|
|
504
|
+
input?.applyDefaultStatus !== false && appliesDefaultStatus(rule, change)
|
|
505
|
+
? rule.defaultStatus
|
|
506
|
+
: null,
|
|
507
|
+
};
|
|
508
|
+
}
|
|
509
|
+
if (policy.defaultEffect === "allow") {
|
|
510
|
+
return { rule: null, id: null, effect: "allow", reason: null, defaultStatus: null };
|
|
511
|
+
}
|
|
512
|
+
return {
|
|
513
|
+
rule: null,
|
|
514
|
+
id: nearest ? nearest.id : null,
|
|
515
|
+
effect: "deny",
|
|
516
|
+
reason: nearest ? `${nearestFailure}_denied` : "actor_denied",
|
|
517
|
+
defaultStatus: null,
|
|
518
|
+
};
|
|
519
|
+
}
|
|
520
|
+
|
|
521
|
+
function violation(ruleId, reason, change, extra) {
|
|
522
|
+
return {
|
|
523
|
+
code: "policy_violation",
|
|
524
|
+
rule: ruleId,
|
|
525
|
+
reason,
|
|
526
|
+
...(extra || {}),
|
|
527
|
+
...(change?.path ? { path: change.path } : {}),
|
|
528
|
+
...(change?.bundleId ? { bundleId: change.bundleId } : {}),
|
|
529
|
+
...(change?.uri ? { uri: change.uri } : {}),
|
|
530
|
+
};
|
|
531
|
+
}
|
|
532
|
+
|
|
533
|
+
// Evaluates one batch. `changes` are { op, bundleId, path, type, frontmatter,
|
|
534
|
+
// uri } descriptors (a planned candidate's fields; see describeChange for raw
|
|
535
|
+
// updates). Returns { violations, decisions }: decisions[i] is { rule, effect,
|
|
536
|
+
// defaultStatus } for changes[i], defaultStatus being the status the caller
|
|
537
|
+
// should stamp on a created concept that set none. A caller that cannot
|
|
538
|
+
// stamp it (a producer, whose bytes are digest-tracked) passes
|
|
539
|
+
// applyDefaultStatus: false, and a required status must then be present.
|
|
540
|
+
//
|
|
541
|
+
// actor null is a write nobody is attributed to (an HTTP call, a proposal
|
|
542
|
+
// stored before an actor was configured). It is judged as the literal actor
|
|
543
|
+
// "unknown", so "*" and "**" match it and a rule can name it explicitly;
|
|
544
|
+
// no real actor has that shape (human:, process:, or provider/model).
|
|
545
|
+
function evaluateWritePolicy(policy, input) {
|
|
546
|
+
const actor = input?.actor === null ? UNKNOWN_ACTOR : input?.actor;
|
|
547
|
+
if (typeof actor !== "string" || !actor.trim()) {
|
|
548
|
+
throw new TypeError("evaluateWritePolicy requires an actor string, or null when unattributed.");
|
|
549
|
+
}
|
|
550
|
+
if (!input || !Array.isArray(input.changes)) {
|
|
551
|
+
throw new TypeError("evaluateWritePolicy requires a changes array.");
|
|
552
|
+
}
|
|
553
|
+
const described = input.changes.map((change, position) =>
|
|
554
|
+
describeChange(change, position, input.index),
|
|
555
|
+
);
|
|
556
|
+
if (!policy) {
|
|
557
|
+
return { violations: [], decisions: described.map(() => null) };
|
|
558
|
+
}
|
|
559
|
+
if (!isWritePolicy(policy)) {
|
|
560
|
+
throw new TypeError("evaluateWritePolicy requires a policy from parseWritePolicy.");
|
|
561
|
+
}
|
|
562
|
+
const decisions = described.map((change) => decide(policy, actor, change, input));
|
|
563
|
+
const violations = [];
|
|
564
|
+
decisions.forEach((decision, position) => {
|
|
565
|
+
const change = described[position];
|
|
566
|
+
if (decision.effect === "deny") {
|
|
567
|
+
violations.push(violation(decision.id, decision.reason, change));
|
|
568
|
+
return;
|
|
569
|
+
}
|
|
570
|
+
if (!decision.rule) return;
|
|
571
|
+
const frontmatter = decision.defaultStatus
|
|
572
|
+
? Object.assign({}, change.frontmatter, { status: decision.defaultStatus })
|
|
573
|
+
: change.frontmatter;
|
|
574
|
+
decision.rule.requiredFields.forEach((field) => {
|
|
575
|
+
// Own keys only: "constructor" or "toString" must not be satisfied by
|
|
576
|
+
// Object.prototype.
|
|
577
|
+
if (!hasOwn(frontmatter, field) || isEmptyValue(frontmatter[field])) {
|
|
578
|
+
violations.push(violation(decision.id, "missing_required_field", change, { field }));
|
|
579
|
+
}
|
|
580
|
+
});
|
|
581
|
+
});
|
|
582
|
+
const counts = new Map();
|
|
583
|
+
decisions.forEach((decision) => {
|
|
584
|
+
if (decision.rule && decision.effect === "allow") {
|
|
585
|
+
counts.set(decision.rule, (counts.get(decision.rule) || 0) + 1);
|
|
586
|
+
}
|
|
587
|
+
});
|
|
588
|
+
policy.rules.forEach((rule) => {
|
|
589
|
+
const count = counts.get(rule) || 0;
|
|
590
|
+
if (rule && rule.maxConceptsPerBatch !== null && count > rule.maxConceptsPerBatch) {
|
|
591
|
+
violations.push(
|
|
592
|
+
violation(rule.id, "batch_too_large", null, {
|
|
593
|
+
limit: rule.maxConceptsPerBatch,
|
|
594
|
+
count,
|
|
595
|
+
}),
|
|
596
|
+
);
|
|
597
|
+
}
|
|
598
|
+
});
|
|
599
|
+
return {
|
|
600
|
+
violations,
|
|
601
|
+
decisions: decisions.map((decision) => ({
|
|
602
|
+
rule: decision.id,
|
|
603
|
+
effect: decision.effect,
|
|
604
|
+
defaultStatus: decision.defaultStatus,
|
|
605
|
+
})),
|
|
606
|
+
};
|
|
607
|
+
}
|
|
608
|
+
|
|
609
|
+
function policyFileError(code, message, details) {
|
|
610
|
+
const error = new Error(message);
|
|
611
|
+
error.code = code;
|
|
612
|
+
if (details !== undefined) error.details = details;
|
|
613
|
+
return error;
|
|
614
|
+
}
|
|
615
|
+
|
|
616
|
+
// `--policy <file>` for --root mode: a YAML (or JSON) mapping holding the
|
|
617
|
+
// writePolicy fields, optionally wrapped in a top-level `writePolicy:` key.
|
|
618
|
+
// Path safety (S-1), as for the vector cache directory: ancestors resolve
|
|
619
|
+
// through their real paths first (a relocated home is common), the file
|
|
620
|
+
// itself must be a regular file and not a symbolic link, and it is opened
|
|
621
|
+
// without following links and checked to be the very file that was
|
|
622
|
+
// inspected, with no symbolic link left anywhere on its resolved path. A
|
|
623
|
+
// component swapped for a link between the check and the read is refused.
|
|
624
|
+
function readPolicyFile(filePath) {
|
|
625
|
+
if (typeof filePath !== "string" || !filePath.trim()) {
|
|
626
|
+
throw policyFileError("invalid_policy_path", "--policy requires a file path.");
|
|
627
|
+
}
|
|
628
|
+
const requested = path.resolve(filePath);
|
|
629
|
+
const resolved = path.join(
|
|
630
|
+
realpathOfExistingAncestors(path.dirname(requested)),
|
|
631
|
+
path.basename(requested),
|
|
632
|
+
);
|
|
633
|
+
let stat;
|
|
634
|
+
try {
|
|
635
|
+
stat = fs.lstatSync(resolved);
|
|
636
|
+
} catch {
|
|
637
|
+
throw policyFileError("policy_file_missing", `Write policy file does not exist: ${resolved}`);
|
|
638
|
+
}
|
|
639
|
+
if (stat.isSymbolicLink()) {
|
|
640
|
+
throw policyFileError("policy_file_symlink", "Write policy file cannot be a symbolic link.");
|
|
641
|
+
}
|
|
642
|
+
if (!stat.isFile()) {
|
|
643
|
+
throw policyFileError("policy_file_not_regular", "Write policy file must be a regular file.");
|
|
644
|
+
}
|
|
645
|
+
if (stat.size > MAX_POLICY_FILE_BYTES) {
|
|
646
|
+
throw policyFileError(
|
|
647
|
+
"policy_file_too_large",
|
|
648
|
+
`Write policy file must not exceed ${MAX_POLICY_FILE_BYTES} bytes.`,
|
|
649
|
+
);
|
|
650
|
+
}
|
|
651
|
+
const descriptor = fs.openSync(resolved, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
|
|
652
|
+
try {
|
|
653
|
+
const opened = fs.fstatSync(descriptor);
|
|
654
|
+
const sameFile = opened.dev === stat.dev && (opened.ino === 0 || opened.ino === stat.ino);
|
|
655
|
+
if (!opened.isFile() || !sameFile || fs.realpathSync(resolved) !== resolved) {
|
|
656
|
+
throw policyFileError(
|
|
657
|
+
"policy_file_symlink",
|
|
658
|
+
"Write policy file path changed or gained a symbolic link while it was read.",
|
|
659
|
+
);
|
|
660
|
+
}
|
|
661
|
+
if (opened.size > MAX_POLICY_FILE_BYTES) {
|
|
662
|
+
throw policyFileError(
|
|
663
|
+
"policy_file_too_large",
|
|
664
|
+
`Write policy file must not exceed ${MAX_POLICY_FILE_BYTES} bytes.`,
|
|
665
|
+
);
|
|
666
|
+
}
|
|
667
|
+
return { resolved, text: fs.readFileSync(descriptor, "utf8") };
|
|
668
|
+
} finally {
|
|
669
|
+
fs.closeSync(descriptor);
|
|
670
|
+
}
|
|
671
|
+
}
|
|
672
|
+
|
|
673
|
+
function loadWritePolicyFile(filePath) {
|
|
674
|
+
const { resolved, text } = readPolicyFile(filePath);
|
|
675
|
+
let raw;
|
|
676
|
+
try {
|
|
677
|
+
raw = resolved.endsWith(".json") ? JSON.parse(text) : parseFrontmatterYaml(text);
|
|
678
|
+
} catch (error) {
|
|
679
|
+
throw policyFileError(
|
|
680
|
+
"invalid_policy_file",
|
|
681
|
+
`Write policy file is not a YAML mapping: ${error.message}`,
|
|
682
|
+
);
|
|
683
|
+
}
|
|
684
|
+
if (raw === undefined || raw === null) {
|
|
685
|
+
throw policyFileError("invalid_policy_file", "Write policy file is empty.");
|
|
686
|
+
}
|
|
687
|
+
const body =
|
|
688
|
+
isPlainObject(raw) && hasOwn(raw, "writePolicy") && Object.keys(raw).length === 1
|
|
689
|
+
? raw.writePolicy
|
|
690
|
+
: raw;
|
|
691
|
+
const parsed = parseWritePolicy(body);
|
|
692
|
+
if (parsed.errors.length || !parsed.policy) {
|
|
693
|
+
const summary = parsed.errors.map((entry) => `${entry.field}: ${entry.message}`).join("; ");
|
|
694
|
+
throw policyFileError(
|
|
695
|
+
"invalid_write_policy",
|
|
696
|
+
`Invalid write policy in ${resolved}: ${summary || "no policy mapping"}`,
|
|
697
|
+
parsed.errors,
|
|
698
|
+
);
|
|
699
|
+
}
|
|
700
|
+
return parsed.policy;
|
|
701
|
+
}
|
|
702
|
+
|
|
703
|
+
module.exports = {
|
|
704
|
+
UNKNOWN_ACTOR,
|
|
705
|
+
evaluateWritePolicy,
|
|
706
|
+
isWritePolicy,
|
|
707
|
+
loadWritePolicyFile,
|
|
708
|
+
parseWritePolicy,
|
|
709
|
+
/** @internal Exposed for the glob subset tests. */
|
|
710
|
+
compileGlobPattern,
|
|
711
|
+
/** @internal */
|
|
712
|
+
globMatch,
|
|
713
|
+
};
|