@crewhaus/tool-state 0.8.0 → 0.8.2
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/README.md +16 -4
- package/dist/index.js +50 -24
- package/dist/store.d.ts +23 -3
- package/dist/store.js +54 -5
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -73,12 +73,24 @@ directory that is not ours.
|
|
|
73
73
|
|
|
74
74
|
`StateImport` never writes the run's own record either (0.8.0): the session
|
|
75
75
|
logs, the tool results the runtime saved to a file, and the proof bundles,
|
|
76
|
-
which the runtime hands each call on its bridge
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
76
|
+
which the runtime hands each call on its bridge with the files that control
|
|
77
|
+
the run (the harness's run files, settings, gate records, environment files,
|
|
78
|
+
compiled bundle and dependencies, Hangar's directory). An import
|
|
79
|
+
with an entry that would land in one is refused, and so is a `replace` of a
|
|
80
|
+
directory that holds one, in every permission mode and before anything is
|
|
81
|
+
written. A `stateDir` of `.crewhaus` would otherwise put an entry such as
|
|
80
82
|
`sessions/<id>.jsonl` in the live session log.
|
|
81
83
|
|
|
84
|
+
The tools here that write check where each record resolves against the same
|
|
85
|
+
roots, and refuse one a link leads into, in every permission mode and before
|
|
86
|
+
anything is written.
|
|
87
|
+
|
|
88
|
+
On a `channel` or `managed` harness, `StateExport` leaves out a file named
|
|
89
|
+
`.env`, `.env.<name>` or `.npmrc` and the credential files the run keeps from
|
|
90
|
+
its tools, and says how many under `heldBack`. There `IndexSearch` reports such a
|
|
91
|
+
file as `missing` with no snippet, and `StateImport` refuses a document that names
|
|
92
|
+
one, whole.
|
|
93
|
+
|
|
82
94
|
**Determinism.** Same inputs against the same state, same bytes out. Listings
|
|
83
95
|
are sorted by plain code-unit comparison — never `localeCompare`, whose order
|
|
84
96
|
depends on the machine's locale. Nothing samples a random source. And **no
|
package/dist/index.js
CHANGED
|
@@ -46,14 +46,14 @@
|
|
|
46
46
|
import { readdirSync, statSync } from "node:fs";
|
|
47
47
|
import * as path from "node:path";
|
|
48
48
|
import { buildTool } from "@crewhaus/tool-builder";
|
|
49
|
-
import { protectedRootBeneath, protectedRootHolding, protectedRootsOf, protectedWriteRefusal, } from "@crewhaus/tool-safety/fs";
|
|
49
|
+
import { credentialRootsOf, gitDirectoryWriteRefusal, heldFileRefusal, isHeldFile, landsInGitDirectory, protectedRootBeneath, protectedRootHolding, protectedRootsOf, protectedWriteRefusal, } from "@crewhaus/tool-safety/fs";
|
|
50
50
|
import { z } from "zod";
|
|
51
51
|
import { DEFAULT_B, DEFAULT_K1, buildIndex, isInvertedIndex, searchIndex, snippet, } from "./lib/bm25";
|
|
52
52
|
import { filterRecords, highestSeq, parseJsonl, toJsonlLine, } from "./lib/jsonl";
|
|
53
53
|
import { MAX_KEY_LENGTH, compareStrings, decodeSegment, encodeSegment, validateKey, validateName, } from "./lib/names";
|
|
54
54
|
import { byteLength, casConflict, expiryFrom, formatInstant, isExpired, isPlainObject, isStoredRecord, parseInstant, } from "./lib/records";
|
|
55
55
|
import { ToolPermissionError, entryNameEscapes, resolveSafe, workspaceRoot, } from "./paths";
|
|
56
|
-
import { DEFAULT_STATE_DIR, MAX_FILE_BYTES, appendLine, createExclusive, describeIoError, errorCode, fileSize, listNames, readBytes, readJsonFile, readTextFile, relativeToRoot, removeFile, removeTree, sha256, statePath, stateRoot, walkFiles, withLock, writeBuffer, writeJsonAtomic, } from "./store";
|
|
56
|
+
import { DEFAULT_STATE_DIR, MAX_FILE_BYTES, ProtectedWriteError, appendLine, createExclusive, describeIoError, errorCode, fileSize, listNames, readBytes, readJsonFile, readTextFile, relativeToRoot, removeFile, removeTree, sha256, statePath, stateRoot, walkFiles, withLock, withProtectedRoots, writeBuffer, writeJsonAtomic, } from "./store";
|
|
57
57
|
import { MAX_VECTOR_IDS, VECTOR_DELETE_EXAMPLE, applyVectorDeletes, capList, checkCollection, countIsIndicative, describeBackend, getVectorTarget, observeCount, readVectorToolConfig, selectVectorIds, unionProtected, } from "./vector";
|
|
58
58
|
/** Compact JSON — the reader is a model, and every byte is context. */
|
|
59
59
|
const json = (value) => JSON.stringify(value);
|
|
@@ -117,11 +117,13 @@ function stateTool(def) {
|
|
|
117
117
|
...def,
|
|
118
118
|
execute: async (input, ctx) => {
|
|
119
119
|
try {
|
|
120
|
-
return await inner(input, ctx);
|
|
120
|
+
return await withProtectedRoots(def.name, protectedRootsOf(ctx), async () => inner(input, ctx));
|
|
121
121
|
}
|
|
122
122
|
catch (err) {
|
|
123
123
|
if (err instanceof ToolPermissionError)
|
|
124
124
|
return err.message;
|
|
125
|
+
if (err instanceof ProtectedWriteError)
|
|
126
|
+
return err.message;
|
|
125
127
|
const io = describeIoError(err);
|
|
126
128
|
if (io !== undefined)
|
|
127
129
|
return `${def.name} could not complete: ${io}`;
|
|
@@ -276,7 +278,7 @@ export const kvSet = stateTool({
|
|
|
276
278
|
stateDir: stateDirField,
|
|
277
279
|
}),
|
|
278
280
|
destructive: true,
|
|
279
|
-
execute: async (input) => {
|
|
281
|
+
execute: async (input, ctx) => {
|
|
280
282
|
const badNamespace = validateName("namespace", input.namespace);
|
|
281
283
|
if (badNamespace !== undefined)
|
|
282
284
|
return badNamespace;
|
|
@@ -294,7 +296,7 @@ export const kvSet = stateTool({
|
|
|
294
296
|
if (input.ttlSeconds !== undefined && now.ms === undefined) {
|
|
295
297
|
return "ttlSeconds needs `now`: expiry is computed from the instant you supply, never from the system clock";
|
|
296
298
|
}
|
|
297
|
-
const root = stateRoot("KvSet", input.stateDir);
|
|
299
|
+
const root = stateRoot("KvSet", input.stateDir, protectedRootsOf(ctx));
|
|
298
300
|
const abs = statePath("KvSet", root, KV_DIR, encodeSegment(input.namespace), `${encodeSegment(input.key)}.json`);
|
|
299
301
|
const rel = relativeToRoot(root, abs);
|
|
300
302
|
const locked = await withLock(`${abs}.lock`, () => {
|
|
@@ -419,14 +421,14 @@ export const kvDelete = stateTool({
|
|
|
419
421
|
stateDir: stateDirField,
|
|
420
422
|
}),
|
|
421
423
|
destructive: true,
|
|
422
|
-
execute: async (input) => {
|
|
424
|
+
execute: async (input, ctx) => {
|
|
423
425
|
const badNamespace = validateName("namespace", input.namespace);
|
|
424
426
|
if (badNamespace !== undefined)
|
|
425
427
|
return badNamespace;
|
|
426
428
|
const badKey = validateKey("key", input.key);
|
|
427
429
|
if (badKey !== undefined)
|
|
428
430
|
return badKey;
|
|
429
|
-
const root = stateRoot("KvDelete", input.stateDir);
|
|
431
|
+
const root = stateRoot("KvDelete", input.stateDir, protectedRootsOf(ctx));
|
|
430
432
|
const abs = statePath("KvDelete", root, KV_DIR, encodeSegment(input.namespace), `${encodeSegment(input.key)}.json`);
|
|
431
433
|
const rel = relativeToRoot(root, abs);
|
|
432
434
|
const locked = await withLock(`${abs}.lock`, () => {
|
|
@@ -563,7 +565,7 @@ export const counterIncrement = stateTool({
|
|
|
563
565
|
stateDir: stateDirField,
|
|
564
566
|
}),
|
|
565
567
|
destructive: true,
|
|
566
|
-
execute: async (input) => {
|
|
568
|
+
execute: async (input, ctx) => {
|
|
567
569
|
const badName = validateName("name", input.name);
|
|
568
570
|
if (badName !== undefined)
|
|
569
571
|
return badName;
|
|
@@ -571,7 +573,7 @@ export const counterIncrement = stateTool({
|
|
|
571
573
|
if (now.error !== undefined)
|
|
572
574
|
return now.error;
|
|
573
575
|
const by = input.by ?? 1;
|
|
574
|
-
const root = stateRoot("CounterIncrement", input.stateDir);
|
|
576
|
+
const root = stateRoot("CounterIncrement", input.stateDir, protectedRootsOf(ctx));
|
|
575
577
|
const abs = statePath("CounterIncrement", root, COUNTER_DIR, `${encodeSegment(input.name)}.json`);
|
|
576
578
|
const rel = relativeToRoot(root, abs);
|
|
577
579
|
const locked = await withLock(`${abs}.lock`, () => {
|
|
@@ -725,7 +727,7 @@ export const checkpointSave = stateTool({
|
|
|
725
727
|
stateDir: stateDirField,
|
|
726
728
|
}),
|
|
727
729
|
destructive: true,
|
|
728
|
-
execute: async (input) => {
|
|
730
|
+
execute: async (input, ctx) => {
|
|
729
731
|
const badName = validateName("name", input.name);
|
|
730
732
|
if (badName !== undefined)
|
|
731
733
|
return badName;
|
|
@@ -738,7 +740,7 @@ export const checkpointSave = stateTool({
|
|
|
738
740
|
const now = parseNow(input.now);
|
|
739
741
|
if (now.error !== undefined)
|
|
740
742
|
return now.error;
|
|
741
|
-
const root = stateRoot("CheckpointSave", input.stateDir);
|
|
743
|
+
const root = stateRoot("CheckpointSave", input.stateDir, protectedRootsOf(ctx));
|
|
742
744
|
const folder = encodeSegment(input.name);
|
|
743
745
|
const dir = statePath("CheckpointSave", root, CHECKPOINT_DIR, folder);
|
|
744
746
|
const locked = await withLock(`${dir}.lock`, () => {
|
|
@@ -914,7 +916,7 @@ export const journalAppend = stateTool({
|
|
|
914
916
|
stateDir: stateDirField,
|
|
915
917
|
}),
|
|
916
918
|
destructive: true,
|
|
917
|
-
execute: async (input) => {
|
|
919
|
+
execute: async (input, ctx) => {
|
|
918
920
|
const badName = validateName("stream", input.stream);
|
|
919
921
|
if (badName !== undefined)
|
|
920
922
|
return badName;
|
|
@@ -924,7 +926,7 @@ export const journalAppend = stateTool({
|
|
|
924
926
|
const now = parseNow(input.now);
|
|
925
927
|
if (now.error !== undefined)
|
|
926
928
|
return now.error;
|
|
927
|
-
const root = stateRoot("JournalAppend", input.stateDir);
|
|
929
|
+
const root = stateRoot("JournalAppend", input.stateDir, protectedRootsOf(ctx));
|
|
928
930
|
const result = await appendSequenced("JournalAppend", root, JOURNAL_DIR, input.stream, (seq) => ({
|
|
929
931
|
seq,
|
|
930
932
|
...(input.kind !== undefined ? { kind: input.kind } : {}),
|
|
@@ -1023,7 +1025,7 @@ export const blackboardPost = stateTool({
|
|
|
1023
1025
|
stateDir: stateDirField,
|
|
1024
1026
|
}),
|
|
1025
1027
|
destructive: true,
|
|
1026
|
-
execute: async (input) => {
|
|
1028
|
+
execute: async (input, ctx) => {
|
|
1027
1029
|
const badTopic = validateName("topic", input.topic);
|
|
1028
1030
|
if (badTopic !== undefined)
|
|
1029
1031
|
return badTopic;
|
|
@@ -1033,7 +1035,7 @@ export const blackboardPost = stateTool({
|
|
|
1033
1035
|
const now = parseNow(input.now);
|
|
1034
1036
|
if (now.error !== undefined)
|
|
1035
1037
|
return now.error;
|
|
1036
|
-
const root = stateRoot("BlackboardPost", input.stateDir);
|
|
1038
|
+
const root = stateRoot("BlackboardPost", input.stateDir, protectedRootsOf(ctx));
|
|
1037
1039
|
const result = await appendSequenced("BlackboardPost", root, BLACKBOARD_DIR, input.topic, (seq) => ({
|
|
1038
1040
|
seq,
|
|
1039
1041
|
author: input.author,
|
|
@@ -1149,14 +1151,14 @@ export const noteWrite = stateTool({
|
|
|
1149
1151
|
stateDir: stateDirField,
|
|
1150
1152
|
}),
|
|
1151
1153
|
destructive: true,
|
|
1152
|
-
execute: async (input) => {
|
|
1154
|
+
execute: async (input, ctx) => {
|
|
1153
1155
|
const badId = validateKey("id", input.id, 200);
|
|
1154
1156
|
if (badId !== undefined)
|
|
1155
1157
|
return badId;
|
|
1156
1158
|
const now = parseNow(input.now);
|
|
1157
1159
|
if (now.error !== undefined)
|
|
1158
1160
|
return now.error;
|
|
1159
|
-
const root = stateRoot("NoteWrite", input.stateDir);
|
|
1161
|
+
const root = stateRoot("NoteWrite", input.stateDir, protectedRootsOf(ctx));
|
|
1160
1162
|
const abs = statePath("NoteWrite", root, NOTE_DIR, `${encodeSegment(input.id)}.json`);
|
|
1161
1163
|
const rel = relativeToRoot(root, abs);
|
|
1162
1164
|
const locked = await withLock(`${abs}.lock`, () => {
|
|
@@ -1322,7 +1324,7 @@ export const indexBuild = stateTool({
|
|
|
1322
1324
|
stateDir: stateDirField,
|
|
1323
1325
|
}),
|
|
1324
1326
|
destructive: true,
|
|
1325
|
-
execute: async (input) => {
|
|
1327
|
+
execute: async (input, ctx) => {
|
|
1326
1328
|
const badName = validateName("name", input.name);
|
|
1327
1329
|
if (badName !== undefined)
|
|
1328
1330
|
return badName;
|
|
@@ -1370,7 +1372,7 @@ export const indexBuild = stateTool({
|
|
|
1370
1372
|
});
|
|
1371
1373
|
}
|
|
1372
1374
|
const index = buildIndex(docs);
|
|
1373
|
-
const root = stateRoot("IndexBuild", input.stateDir);
|
|
1375
|
+
const root = stateRoot("IndexBuild", input.stateDir, protectedRootsOf(ctx));
|
|
1374
1376
|
const abs = statePath("IndexBuild", root, INDEX_DIR, `${encodeSegment(input.name)}.json`);
|
|
1375
1377
|
// Serialise first and check the size: `IndexSearch` reads with a cap, so
|
|
1376
1378
|
// an index written over it would be built successfully and then be
|
|
@@ -1431,7 +1433,7 @@ export const indexSearch = stateTool({
|
|
|
1431
1433
|
}),
|
|
1432
1434
|
readOnly: true,
|
|
1433
1435
|
concurrencySafe: true,
|
|
1434
|
-
execute: async (input) => {
|
|
1436
|
+
execute: async (input, ctx) => {
|
|
1435
1437
|
const badName = validateName("name", input.name);
|
|
1436
1438
|
if (badName !== undefined)
|
|
1437
1439
|
return badName;
|
|
@@ -1456,11 +1458,20 @@ export const indexSearch = stateTool({
|
|
|
1456
1458
|
...(input.minScore !== undefined ? { minScore: input.minScore } : {}),
|
|
1457
1459
|
});
|
|
1458
1460
|
const snippetChars = input.snippetChars ?? 0;
|
|
1461
|
+
const held = credentialRootsOf(ctx);
|
|
1459
1462
|
const hits = result.hits.map((hit) => {
|
|
1460
1463
|
let state = "current";
|
|
1461
1464
|
let text;
|
|
1462
1465
|
try {
|
|
1463
1466
|
const safe = resolveSafe("IndexSearch", hit.id);
|
|
1467
|
+
if (held.length > 0 && isHeldFile(safe.abs, held)) {
|
|
1468
|
+
return {
|
|
1469
|
+
path: hit.id,
|
|
1470
|
+
score: hit.score,
|
|
1471
|
+
matchedTerms: hit.matchedTerms,
|
|
1472
|
+
file: "missing",
|
|
1473
|
+
};
|
|
1474
|
+
}
|
|
1464
1475
|
const stats = statSync(safe.abs);
|
|
1465
1476
|
const sizeChanged = hit.entry.bytes !== undefined && hit.entry.bytes !== stats.size;
|
|
1466
1477
|
const timeChanged = hit.entry.mtimeMs !== undefined && hit.entry.mtimeMs !== Math.round(stats.mtimeMs);
|
|
@@ -1547,10 +1558,15 @@ export const stateExport = stateTool({
|
|
|
1547
1558
|
}),
|
|
1548
1559
|
readOnly: true,
|
|
1549
1560
|
concurrencySafe: true,
|
|
1550
|
-
execute: async (input) => {
|
|
1561
|
+
execute: async (input, ctx) => {
|
|
1551
1562
|
const root = stateRoot("StateExport", input.stateDir);
|
|
1552
1563
|
const { files, truncated } = walkFiles(root.abs, MAX_EXPORT_FILES);
|
|
1553
|
-
const
|
|
1564
|
+
const asked = files.filter((file) => input.prefix === undefined || file.path.startsWith(input.prefix));
|
|
1565
|
+
// A run that keeps files from its tools gets a document without them, and
|
|
1566
|
+
// the count of what it left out: a refusal would give it no document at all.
|
|
1567
|
+
const held = credentialRootsOf(ctx);
|
|
1568
|
+
const selected = held.length === 0 ? asked : asked.filter((file) => !isHeldFile(file.abs, held));
|
|
1569
|
+
const heldBack = asked.length - selected.length;
|
|
1554
1570
|
const totalBytes = selected.reduce((sum, file) => sum + file.bytes, 0);
|
|
1555
1571
|
if (totalBytes > MAX_EXPORT_BYTES) {
|
|
1556
1572
|
return `the state directory holds ${totalBytes} bytes, over the ${MAX_EXPORT_BYTES} export limit — narrow it with \`prefix\`, or copy the directory with the filesystem tools instead`;
|
|
@@ -1596,6 +1612,7 @@ export const stateExport = stateTool({
|
|
|
1596
1612
|
truncated,
|
|
1597
1613
|
files: entries,
|
|
1598
1614
|
...(unreadable.length > 0 ? { unreadable } : {}),
|
|
1615
|
+
...(heldBack > 0 ? { heldBack } : {}),
|
|
1599
1616
|
});
|
|
1600
1617
|
},
|
|
1601
1618
|
});
|
|
@@ -1635,6 +1652,7 @@ export const stateImport = stateTool({
|
|
|
1635
1652
|
// forged fetch grounds any text. Refused in every mode, before anything
|
|
1636
1653
|
// is written, as CopyPath and MovePath refuse.
|
|
1637
1654
|
const protectedRoots = protectedRootsOf(ctx);
|
|
1655
|
+
const held = credentialRootsOf(ctx);
|
|
1638
1656
|
if (mode === "replace" &&
|
|
1639
1657
|
protectedRoots.length > 0 &&
|
|
1640
1658
|
protectedRootBeneath(root.abs, protectedRoots) !== undefined) {
|
|
@@ -1665,6 +1683,14 @@ export const stateImport = stateTool({
|
|
|
1665
1683
|
if (protectedRoots.length > 0 && protectedRootHolding(target, protectedRoots) !== undefined) {
|
|
1666
1684
|
return protectedWriteRefusal("StateImport", `importing ${file.path}`);
|
|
1667
1685
|
}
|
|
1686
|
+
// Read with the state directory in front: `config` imported to `.git` has
|
|
1687
|
+
// no such name of its own, and neither does an entry behind a link.
|
|
1688
|
+
if (protectedRoots.length > 0 && landsInGitDirectory(target)) {
|
|
1689
|
+
return gitDirectoryWriteRefusal("StateImport", `importing ${file.path}`);
|
|
1690
|
+
}
|
|
1691
|
+
if (held.length > 0 && isHeldFile(target, held)) {
|
|
1692
|
+
return heldFileRefusal("StateImport", `importing ${file.path}`);
|
|
1693
|
+
}
|
|
1668
1694
|
const body = file.encoding === "utf8"
|
|
1669
1695
|
? Buffer.from(file.content, "utf8")
|
|
1670
1696
|
: Buffer.from(file.content, "base64");
|
|
@@ -1728,7 +1754,7 @@ export const dedupeMark = stateTool({
|
|
|
1728
1754
|
stateDir: stateDirField,
|
|
1729
1755
|
}),
|
|
1730
1756
|
destructive: true,
|
|
1731
|
-
execute: async (input) => {
|
|
1757
|
+
execute: async (input, ctx) => {
|
|
1732
1758
|
const badScope = validateName("scope", input.scope);
|
|
1733
1759
|
if (badScope !== undefined)
|
|
1734
1760
|
return badScope;
|
|
@@ -1738,7 +1764,7 @@ export const dedupeMark = stateTool({
|
|
|
1738
1764
|
const now = parseNow(input.now);
|
|
1739
1765
|
if (now.error !== undefined)
|
|
1740
1766
|
return now.error;
|
|
1741
|
-
const root = stateRoot("DedupeMark", input.stateDir);
|
|
1767
|
+
const root = stateRoot("DedupeMark", input.stateDir, protectedRootsOf(ctx));
|
|
1742
1768
|
const abs = statePath("DedupeMark", root, DEDUPE_DIR, encodeSegment(input.scope), `${encodeSegment(input.id)}.json`);
|
|
1743
1769
|
const rel = relativeToRoot(root, abs);
|
|
1744
1770
|
if (input.peek === true) {
|
package/dist/store.d.ts
CHANGED
|
@@ -10,6 +10,16 @@ export declare const LOCK_WAIT_MS = 2000;
|
|
|
10
10
|
export declare const LOCK_STALE_MS = 30000;
|
|
11
11
|
/** How deep a walk of the state directory goes before it calls it truncated. */
|
|
12
12
|
export declare const MAX_WALK_DEPTH = 32;
|
|
13
|
+
/** A write this package refused because it resolves into a protected root. */
|
|
14
|
+
export declare class ProtectedWriteError extends Error {
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Run one tool call with the run's protected roots in force: while it runs,
|
|
18
|
+
* every write helper below refuses a path that resolves into one, wherever a
|
|
19
|
+
* link on the way leads. The state directory can sit anywhere in the workspace,
|
|
20
|
+
* so naming `stateDir` says nothing about where a file under it lands.
|
|
21
|
+
*/
|
|
22
|
+
export declare function withProtectedRoots<T>(tool: string, roots: readonly string[], run: () => Promise<T>): Promise<T>;
|
|
13
23
|
/** The outcome of reading a file that may legitimately be absent or broken. */
|
|
14
24
|
export type ReadOutcome<T> = {
|
|
15
25
|
readonly kind: "ok";
|
|
@@ -21,11 +31,18 @@ export type ReadOutcome<T> = {
|
|
|
21
31
|
readonly kind: "corrupt";
|
|
22
32
|
readonly reason: string;
|
|
23
33
|
};
|
|
34
|
+
/** A state directory, and the roots a call that writes beneath it keeps out of. */
|
|
35
|
+
export type StateRoot = SafePath & {
|
|
36
|
+
readonly protectedRoots?: readonly string[];
|
|
37
|
+
};
|
|
24
38
|
/**
|
|
25
39
|
* Resolve the state directory for this call. Throws `ToolPermissionError`
|
|
26
|
-
* when the caller points it outside the workspace.
|
|
40
|
+
* when the caller points it outside the workspace. A tool that writes passes
|
|
41
|
+
* the roots on its call's bridge, and every interior path it then asks for is
|
|
42
|
+
* held to them: the floor reads the directory the call names, and where a
|
|
43
|
+
* record lands beneath it is read here.
|
|
27
44
|
*/
|
|
28
|
-
export declare function stateRoot(toolName: string, stateDir: string | undefined):
|
|
45
|
+
export declare function stateRoot(toolName: string, stateDir: string | undefined, protectedRoots?: readonly string[]): StateRoot;
|
|
29
46
|
/**
|
|
30
47
|
* Join segments beneath the state root and check containment BOTH ways.
|
|
31
48
|
*
|
|
@@ -40,8 +57,11 @@ export declare function stateRoot(toolName: string, stateDir: string | undefined
|
|
|
40
57
|
* The returned path is the lexical one, which is what the result messages and
|
|
41
58
|
* `relativeToRoot` are expressed in; the residual check-to-use window is the
|
|
42
59
|
* usual one, and is narrower than the lifetime of any single tool call.
|
|
60
|
+
*
|
|
61
|
+
* For a root opened to write, a path that resolves into a protected root
|
|
62
|
+
* through a link is refused here, before anything is opened or created.
|
|
43
63
|
*/
|
|
44
|
-
export declare function statePath(toolName: string, root:
|
|
64
|
+
export declare function statePath(toolName: string, root: StateRoot, ...segments: string[]): string;
|
|
45
65
|
/** Path relative to the state root, `/`-separated, for echoing in results. */
|
|
46
66
|
export declare function relativeToRoot(root: SafePath, abs: string): string;
|
|
47
67
|
export declare function ensureDir(abs: string): void;
|
package/dist/store.js
CHANGED
|
@@ -30,11 +30,13 @@
|
|
|
30
30
|
* `O_APPEND` gives, which is atomic per write on local filesystems but not
|
|
31
31
|
* guaranteed on network ones.
|
|
32
32
|
*/
|
|
33
|
+
import { AsyncLocalStorage } from "node:async_hooks";
|
|
33
34
|
import { createHash } from "node:crypto";
|
|
34
35
|
import { closeSync, mkdirSync, openSync, readSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeSync, } from "node:fs";
|
|
35
36
|
import * as path from "node:path";
|
|
37
|
+
import { protectedRootHolding, protectedRootLinkedInto, protectedWriteRefusal, } from "@crewhaus/tool-safety/fs";
|
|
36
38
|
import { compareStrings } from "./lib/names";
|
|
37
|
-
import { ToolPermissionError, isInside, resolveSafe, resolveWithin, toPosix, } from "./paths";
|
|
39
|
+
import { ToolPermissionError, isInside, resolveSafe, resolveWithin, toPosix, workspaceRoot, } from "./paths";
|
|
38
40
|
/** Where state lives when the caller does not say otherwise. */
|
|
39
41
|
export const DEFAULT_STATE_DIR = ".crewhaus/state";
|
|
40
42
|
/** Largest single record, index or export file this package will read. */
|
|
@@ -45,12 +47,45 @@ export const LOCK_WAIT_MS = 2_000;
|
|
|
45
47
|
export const LOCK_STALE_MS = 30_000;
|
|
46
48
|
/** How deep a walk of the state directory goes before it calls it truncated. */
|
|
47
49
|
export const MAX_WALK_DEPTH = 32;
|
|
50
|
+
/** A write this package refused because it resolves into a protected root. */
|
|
51
|
+
export class ProtectedWriteError extends Error {
|
|
52
|
+
}
|
|
53
|
+
const protectedWrites = new AsyncLocalStorage();
|
|
54
|
+
/**
|
|
55
|
+
* Run one tool call with the run's protected roots in force: while it runs,
|
|
56
|
+
* every write helper below refuses a path that resolves into one, wherever a
|
|
57
|
+
* link on the way leads. The state directory can sit anywhere in the workspace,
|
|
58
|
+
* so naming `stateDir` says nothing about where a file under it lands.
|
|
59
|
+
*/
|
|
60
|
+
export function withProtectedRoots(tool, roots, run) {
|
|
61
|
+
return roots.length > 0 ? protectedWrites.run({ tool, roots }, run) : run();
|
|
62
|
+
}
|
|
63
|
+
function refuseProtected(abs) {
|
|
64
|
+
const scope = protectedWrites.getStore();
|
|
65
|
+
if (scope !== undefined && protectedRootHolding(abs, scope.roots) !== undefined) {
|
|
66
|
+
throw new ProtectedWriteError(protectedWriteRefusal(scope.tool, "this call"));
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
/**
|
|
70
|
+
* Raised by {@link statePath} when a link would carry a write into a protected
|
|
71
|
+
* root. Its message is the refusal the tool returns.
|
|
72
|
+
*/
|
|
73
|
+
class ProtectedStateWrite extends ToolPermissionError {
|
|
74
|
+
constructor(toolName, label) {
|
|
75
|
+
super(toolName, label);
|
|
76
|
+
this.message = protectedWriteRefusal(toolName, `"${label}"`);
|
|
77
|
+
}
|
|
78
|
+
}
|
|
48
79
|
/**
|
|
49
80
|
* Resolve the state directory for this call. Throws `ToolPermissionError`
|
|
50
|
-
* when the caller points it outside the workspace.
|
|
81
|
+
* when the caller points it outside the workspace. A tool that writes passes
|
|
82
|
+
* the roots on its call's bridge, and every interior path it then asks for is
|
|
83
|
+
* held to them: the floor reads the directory the call names, and where a
|
|
84
|
+
* record lands beneath it is read here.
|
|
51
85
|
*/
|
|
52
|
-
export function stateRoot(toolName, stateDir) {
|
|
53
|
-
|
|
86
|
+
export function stateRoot(toolName, stateDir, protectedRoots = []) {
|
|
87
|
+
const root = resolveSafe(toolName, stateDir ?? DEFAULT_STATE_DIR);
|
|
88
|
+
return protectedRoots.length > 0 ? { ...root, protectedRoots } : root;
|
|
54
89
|
}
|
|
55
90
|
/**
|
|
56
91
|
* Join segments beneath the state root and check containment BOTH ways.
|
|
@@ -66,6 +101,9 @@ export function stateRoot(toolName, stateDir) {
|
|
|
66
101
|
* The returned path is the lexical one, which is what the result messages and
|
|
67
102
|
* `relativeToRoot` are expressed in; the residual check-to-use window is the
|
|
68
103
|
* usual one, and is narrower than the lifetime of any single tool call.
|
|
104
|
+
*
|
|
105
|
+
* For a root opened to write, a path that resolves into a protected root
|
|
106
|
+
* through a link is refused here, before anything is opened or created.
|
|
69
107
|
*/
|
|
70
108
|
export function statePath(toolName, root, ...segments) {
|
|
71
109
|
const label = segments.join("/");
|
|
@@ -76,7 +114,11 @@ export function statePath(toolName, root, ...segments) {
|
|
|
76
114
|
const joined = path.join(root.abs, segments.filter((s) => s !== "").join(path.sep));
|
|
77
115
|
if (!isInside(root.abs, joined))
|
|
78
116
|
throw new ToolPermissionError(toolName, label);
|
|
79
|
-
resolveWithin(toolName, root.real, joined, label);
|
|
117
|
+
const landsAt = resolveWithin(toolName, root.real, joined, label);
|
|
118
|
+
if (root.protectedRoots !== undefined &&
|
|
119
|
+
protectedRootLinkedInto(joined, landsAt, root.protectedRoots, workspaceRoot()) !== undefined) {
|
|
120
|
+
throw new ProtectedStateWrite(toolName, label);
|
|
121
|
+
}
|
|
80
122
|
return joined;
|
|
81
123
|
}
|
|
82
124
|
/** Path relative to the state root, `/`-separated, for echoing in results. */
|
|
@@ -189,6 +231,7 @@ let tempCounter = 0;
|
|
|
189
231
|
* random suffix, so a crashed run leaves a name you can recognise.
|
|
190
232
|
*/
|
|
191
233
|
export function writeJsonAtomic(abs, value) {
|
|
234
|
+
refuseProtected(abs);
|
|
192
235
|
ensureDir(path.dirname(abs));
|
|
193
236
|
const body = `${JSON.stringify(value)}\n`;
|
|
194
237
|
tempCounter += 1;
|
|
@@ -220,6 +263,7 @@ export function writeJsonAtomic(abs, value) {
|
|
|
220
263
|
* other's lines.
|
|
221
264
|
*/
|
|
222
265
|
export function appendLine(abs, line) {
|
|
266
|
+
refuseProtected(abs);
|
|
223
267
|
ensureDir(path.dirname(abs));
|
|
224
268
|
const fd = openSync(abs, "a");
|
|
225
269
|
try {
|
|
@@ -235,6 +279,7 @@ export function appendLine(abs, line) {
|
|
|
235
279
|
* exactly one caller can win, with no lock involved.
|
|
236
280
|
*/
|
|
237
281
|
export function createExclusive(abs, body) {
|
|
282
|
+
refuseProtected(abs);
|
|
238
283
|
ensureDir(path.dirname(abs));
|
|
239
284
|
let fd;
|
|
240
285
|
try {
|
|
@@ -261,6 +306,7 @@ export function createExclusive(abs, body) {
|
|
|
261
306
|
* workspace from clobbering a counter. It is not a distributed lock.
|
|
262
307
|
*/
|
|
263
308
|
export async function withLock(lockPath, body, waitMs = LOCK_WAIT_MS) {
|
|
309
|
+
refuseProtected(lockPath);
|
|
264
310
|
ensureDir(path.dirname(lockPath));
|
|
265
311
|
const deadline = Date.now() + waitMs;
|
|
266
312
|
for (;;) {
|
|
@@ -400,6 +446,7 @@ export function fileSize(abs) {
|
|
|
400
446
|
}
|
|
401
447
|
/** Remove a file, reporting whether it was there. */
|
|
402
448
|
export function removeFile(abs) {
|
|
449
|
+
refuseProtected(abs);
|
|
403
450
|
try {
|
|
404
451
|
unlinkSync(abs);
|
|
405
452
|
return true;
|
|
@@ -412,6 +459,7 @@ export function removeFile(abs) {
|
|
|
412
459
|
}
|
|
413
460
|
/** Remove a directory tree. Used only by `StateImport` in replace mode. */
|
|
414
461
|
export function removeTree(abs) {
|
|
462
|
+
refuseProtected(abs);
|
|
415
463
|
rmSync(abs, { recursive: true, force: true });
|
|
416
464
|
}
|
|
417
465
|
export function sha256(text) {
|
|
@@ -461,6 +509,7 @@ export function describeIoError(err) {
|
|
|
461
509
|
* used only by `StateImport` when restoring a base64-carried entry.
|
|
462
510
|
*/
|
|
463
511
|
export function writeBuffer(abs, body) {
|
|
512
|
+
refuseProtected(abs);
|
|
464
513
|
ensureDir(path.dirname(abs));
|
|
465
514
|
tempCounter += 1;
|
|
466
515
|
const temp = `${abs}.tmp-${process.pid}-${tempCounter}`;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@crewhaus/tool-state",
|
|
3
|
-
"version": "0.8.
|
|
3
|
+
"version": "0.8.2",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Deterministic harness state tools: key-value storage, counters, checkpoints, journals, blackboards and lexical search over local notes",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -16,11 +16,11 @@
|
|
|
16
16
|
"test": "bun test src"
|
|
17
17
|
},
|
|
18
18
|
"dependencies": {
|
|
19
|
-
"@crewhaus/errors": "0.8.
|
|
20
|
-
"@crewhaus/tool-builder": "0.8.
|
|
21
|
-
"@crewhaus/tool-catalog": "0.8.
|
|
22
|
-
"@crewhaus/tool-safety": "0.8.
|
|
23
|
-
"@crewhaus/vector-store": "0.8.
|
|
19
|
+
"@crewhaus/errors": "0.8.2",
|
|
20
|
+
"@crewhaus/tool-builder": "0.8.2",
|
|
21
|
+
"@crewhaus/tool-catalog": "0.8.2",
|
|
22
|
+
"@crewhaus/tool-safety": "0.8.2",
|
|
23
|
+
"@crewhaus/vector-store": "0.8.2",
|
|
24
24
|
"zod": "^3.23.8"
|
|
25
25
|
},
|
|
26
26
|
"devDependencies": {
|