@raibitsi/tiresias 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/guard.js ADDED
@@ -0,0 +1,1240 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ // W-38 (v1.2): the meaning check. Local mode's pattern list (aimedSignals in local.ts) sees only the shapes it
3
+ // knows. This check asks the owner's OWN embedding model how close a passage is in meaning to known planted
4
+ // instructions, against how close it is to ordinary page text:
5
+ //
6
+ // score for a collection = (highest cosine to that collection) minus (highest cosine to any ordinary passage)
7
+ //
8
+ // Each collection (the starter, and each set the owner imports) has its own alarm line, and a passage above any
9
+ // one of them is marked, so adding a collection can only add marks (see calibration, below).
10
+ //
11
+ // Measured with EmbeddingGemma 2 (SPEC W-38): an attack library alone, with no ordinary library, caught 1 of 29
12
+ // planted tricks at 1 false alarm in 100, because the topic dominates the vector; the difference of the two
13
+ // libraries caught 28 of 29 with page style examples of the same tricks, and 19 of 29 when the library held other
14
+ // tricks only. Whole passages scored as well as sentence by sentence, so whole passages are scored.
15
+ //
16
+ // Off until the owner sets it up (tiresias guard setup), from the command line only. Tiresias bundles no model, the
17
+ // same stance as the scanner (W-21). Nothing reachable over MCP reads, sets, changes or triggers it, and nothing from
18
+ // the libraries (texts, scores, collection names) ever reaches a reply: a passage above a collection's line gets ONE more
19
+ // sign in local mode's own count, so it is warned (or withheld with a pattern sign) by the rules already there.
20
+ //
21
+ // The library lives in the profile's guard/ folder, under the store's usual checks: vectors as Float32 (unit
22
+ // length) in attacks.f32 and ordinary.f32, one metadata line per vector (collection, kind, a hash; no text) in
23
+ // attacks.jsonl and ordinary.jsonl, the owner's imported attack texts in imported.jsonl (so a rebuild for another
24
+ // model can embed them again), and meta.json, written last, with each collection's line, which rows belong to which
25
+ // collection, and the sizes and SHA-256 of both vector files. A
26
+ // reader that finds anything that does not add up treats the check as not run; it never fails a read.
27
+ import { createHash, randomBytes } from "node:crypto";
28
+ import fs from "node:fs";
29
+ import path from "node:path";
30
+ import { fileURLToPath } from "node:url";
31
+ import { setImmediate as yieldScoring } from "node:timers/promises";
32
+ import { ConfigError, GUARD_TIMEOUT, loadGuard, parseGuardUrl, readConfigObject } from "./config.js";
33
+ import { GUARD_PHRASE, asking, confirmedWrite, refusal, sq } from "./confirm.js";
34
+ import { LruMap } from "./lru.js";
35
+ import { isOwnerAddress } from "./guardnetwork.js";
36
+ import { NOFOLLOW, NONBLOCK, checkSub, home, ownFile, readBounded, readOwnedText, sessionPrivate, subDir, writeJson } from "./store.js";
37
+ import { EmbedError, MAX_BATCH, MAX_DIM, MAX_INPUT_CHARS, MIN_DIM, classify, embed, embedAll } from "./guardclient.js";
38
+ import { releaseLock, stillOwned, takeLock } from "./ownedlock.js";
39
+ export const GUARD_DIR = "guard";
40
+ const F = { meta: "meta.json", attacks: "attacks.f32", attackRows: "attacks.jsonl", imported: "imported.jsonl", ordinary: "ordinary.f32", ordinaryRows: "ordinary.jsonl" };
41
+ // Bounds on what setup and import accept.
42
+ export const MIN_ORDINARY = 300; // ordinary passages, at least, to calibrate on
43
+ export const MIN_ORDINARY_PAGES = 20; // pages they come from, at least (the split is by page)
44
+ export const MIN_ABOVE_LINE = 2; // the pooled calibration passages must put at least this many at or above each line
45
+ export const MIN_ATTACKS = 100;
46
+ export const MAX_ORDINARY = 6_000;
47
+ export const MAX_PER_PAGE = 40;
48
+ export const MAX_ATTACKS = 30_000;
49
+ export const MAX_IMPORT = 10_000; // texts in one import
50
+ export const MAX_IMPORT_BYTES = 32 * 1024 * 1024;
51
+ export const MIN_TEXT = 10;
52
+ export const MAX_TEXT = 4_000;
53
+ export const MIN_PASSAGE = 40; // characters: shorter page text is never sent (headings, labels, scraps)
54
+ export const MAX_PASSAGE = 2_000; // an ordinary passage is cut here when gathered
55
+ export const SECTIONS_PER_PAGE = 4; // setup reads the first few sections of each ordinary page
56
+ export const MAX_URLS = 1_000;
57
+ export const DEFAULT_FALSE_ALARMS = 1;
58
+ export const SELF_TEST_FLOOR = 1 / 3; // below this share of unseen starter tricks caught, setup warns
59
+ export const IMPORT_FLOOR = 0.1; // an import that marks under this share of starter texts on its own adds little for page text
60
+ const SETUP_TIMEOUT_MS = 120_000; // one batch during setup, import or check (a model may be loading)
61
+ // The prefix the 2026-11-14 measurements used for EmbeddingGemma: it is a default only, and --prefix always wins.
62
+ export const GEMMA_PREFIX = "task: classification | query: ";
63
+ export const defaultPrefix = (model) => (/embeddinggemma/i.test(model) ? GEMMA_PREFIX : "");
64
+ // ---- the package's own data ----
65
+ const dataFile = (name) => fileURLToPath(new URL(`../data/${name}`, import.meta.url));
66
+ export const STARTER_KINDS = ["override", "fake_system", "fake_user", "fake_tool", "fake_assistant", "chat_marks", "send_out", "reply_shape", "favour", "task_changed", "fake_rule", "urgency", "persona", "secrecy", "conditional"];
67
+ // The starter set shipped in data/guard-starter.jsonl: test strings for this detector, written for Tiresias.
68
+ export function starter() {
69
+ const out = [];
70
+ for (const line of fs.readFileSync(dataFile("guard-starter.jsonl"), "utf8").split("\n")) {
71
+ if (!line.trim())
72
+ continue;
73
+ const o = JSON.parse(line);
74
+ if (typeof o.text !== "string" || !STARTER_KINDS.includes(o.kind))
75
+ throw new Error("data/guard-starter.jsonl has a bad line.");
76
+ out.push({ text: o.text, kind: o.kind });
77
+ }
78
+ return out;
79
+ }
80
+ export const bundledUrlList = () => dataFile("guard-ordinary-urls.txt");
81
+ // ---- hashing and the vectors ----
82
+ // One text's identity: whitespace folded, so the same text copied twice counts once.
83
+ export const textHash = (t) => createHash("sha256").update(t.trim().replace(/\s+/g, " ")).digest("hex").slice(0, 32);
84
+ const fileHash = (b) => createHash("sha256").update(b).digest("hex");
85
+ const toBuffer = (vs, dim) => {
86
+ const b = Buffer.alloc(vs.length * dim * 4);
87
+ vs.forEach((v, i) => Buffer.from(v.buffer, v.byteOffset, v.byteLength).copy(b, i * dim * 4));
88
+ return b;
89
+ };
90
+ const toMatrix = (b) => {
91
+ const copy = new ArrayBuffer(b.length);
92
+ new Uint8Array(copy).set(b);
93
+ return new Float32Array(copy);
94
+ };
95
+ // The highest dot product of v with any row of m (rows of length dim), skipping rows `skip` says to.
96
+ // `start` and `count` limit it to a run of rows.
97
+ function maxDot(v, m, dim, skip, start = 0, count = m.length / dim - start) {
98
+ let best = -Infinity;
99
+ for (let r = start; r < start + count; r++) {
100
+ if (skip?.(r))
101
+ continue;
102
+ let s = 0;
103
+ const o = r * dim;
104
+ for (let i = 0; i < dim; i++)
105
+ s += v[i] * m[o + i];
106
+ if (s > best)
107
+ best = s;
108
+ }
109
+ return best;
110
+ }
111
+ export class LibraryError extends Error {
112
+ }
113
+ const MAX_META = 1024 * 1024;
114
+ const MAX_VECTORS_BYTES = 512 * 1024 * 1024;
115
+ const MAX_ROWS_BYTES = 64 * 1024 * 1024;
116
+ // v1.2 (L.7): guard commands share one owned lock beside the folder, including off. Network work holds no lock:
117
+ // the setting, file stamps and revision are compared again before committing. The revision survives off, so even
118
+ // off on an empty store cancels a setup that was already gathering text.
119
+ const REVISION = "guard-state.json";
120
+ function withGuardLock(fn) {
121
+ const file = path.join(home(), GUARD_DIR);
122
+ const token = takeLock(file);
123
+ if (!token)
124
+ throw new ConfigError(`The guard is being changed by another Tiresias command (${file}.lock). Try again in a moment. If no other Tiresias command is running, delete the abandoned lock with rm ${sq(file + ".lock")} and try again.`);
125
+ try {
126
+ if (!stillOwned(file, token))
127
+ throw new ConfigError("The guard lock was removed. Nothing was written.");
128
+ return fn();
129
+ }
130
+ finally {
131
+ releaseLock(file, token);
132
+ }
133
+ }
134
+ function guardState() {
135
+ const dir = subDir(GUARD_DIR, false);
136
+ let effective;
137
+ try {
138
+ effective = loadGuard(isOwnerAddress);
139
+ }
140
+ catch {
141
+ // Setup can repair a bad setting; its raw value below still participates in the comparison.
142
+ }
143
+ const stamps = Object.values(F).map((name) => {
144
+ if (!dir)
145
+ return null;
146
+ try {
147
+ const s = fs.lstatSync(path.join(dir, name));
148
+ return [s.dev, s.ino, s.size, s.mtimeMs, s.ctimeMs, s.mode];
149
+ }
150
+ catch (e) {
151
+ if (e.code === "ENOENT")
152
+ return null;
153
+ throw e;
154
+ }
155
+ });
156
+ return JSON.stringify([readConfigObject()?.guard, effective, readOwnedText(REVISION), stamps]);
157
+ }
158
+ function unchangedGuard(state) {
159
+ let same = false;
160
+ try {
161
+ same = guardState() === state;
162
+ }
163
+ catch {
164
+ // A setting or folder that became unreadable is also a change, never permission to replace it.
165
+ }
166
+ if (!same)
167
+ throw new ConfigError("The guard setting or library changed while this command was running. Nothing was written. Run the command again if you still want this change.");
168
+ }
169
+ const advanceGuard = () => writeJson(path.join(home(), REVISION), randomBytes(16).toString("hex"));
170
+ // v1.2 (L.8): never build a vector file the reader cannot load. Check the dimension before doing arithmetic.
171
+ function vectorBudget(dim, attacks, ordinary) {
172
+ if (!Number.isInteger(dim) || dim < MIN_DIM || dim > MAX_DIM)
173
+ throw new ConfigError(`The embedding dimension must be from ${MIN_DIM} to ${MAX_DIM}. Nothing was changed.`);
174
+ for (const [kind, count] of [["attack", attacks], ["ordinary", ordinary]]) {
175
+ const bytes = count * dim * 4;
176
+ if (!Number.isSafeInteger(count) || count < 0 || !Number.isSafeInteger(bytes) || bytes > MAX_VECTORS_BYTES)
177
+ throw new ConfigError(`At dimension ${dim}, ${count} ${kind} vectors need ${bytes} bytes; the limit is ${MAX_VECTORS_BYTES} bytes (${Math.floor(MAX_VECTORS_BYTES / (dim * 4))} vectors). Nothing was changed.`);
178
+ }
179
+ if (attacks > MAX_ATTACKS)
180
+ throw new ConfigError(`The attack library would have ${attacks} texts; the limit is ${MAX_ATTACKS}. Nothing was changed.`);
181
+ }
182
+ // Read one file of guard/: a plain file of ours, never through a link, bounded. Missing is null.
183
+ function readGuardFile(name, max) {
184
+ const dir = subDir(GUARD_DIR, false);
185
+ if (!dir)
186
+ return null;
187
+ const file = path.join(dir, name);
188
+ let fd;
189
+ try {
190
+ fd = fs.openSync(file, fs.constants.O_RDONLY | NOFOLLOW | NONBLOCK);
191
+ }
192
+ catch (e) {
193
+ if (e.code === "ENOENT")
194
+ return null;
195
+ throw new LibraryError(`guard/${name} cannot be read.`);
196
+ }
197
+ try {
198
+ ownFile(fd, file);
199
+ const b = readBounded(fd, max);
200
+ if (b === null)
201
+ throw new LibraryError(`guard/${name} is larger than allowed.`);
202
+ return b;
203
+ }
204
+ finally {
205
+ fs.closeSync(fd);
206
+ }
207
+ }
208
+ // Write one file of guard/ atomically: an exclusive temp file (never through a link), mode 0600, then a rename.
209
+ function writeGuardFile(name, data) {
210
+ const dir = subDir(GUARD_DIR, true);
211
+ const file = path.join(dir, name);
212
+ const tmp = `${file}.${randomBytes(8).toString("hex")}.tmp`;
213
+ const fd = fs.openSync(tmp, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | NOFOLLOW | NONBLOCK, 0o600);
214
+ try {
215
+ ownFile(fd, tmp);
216
+ for (let off = 0; off < data.length;)
217
+ off += fs.writeSync(fd, data, off, data.length - off);
218
+ fs.fsyncSync(fd);
219
+ }
220
+ catch (e) {
221
+ fs.closeSync(fd);
222
+ fs.rmSync(tmp, { force: true });
223
+ throw e;
224
+ }
225
+ fs.closeSync(fd);
226
+ try {
227
+ fs.renameSync(tmp, file);
228
+ }
229
+ catch (e) {
230
+ fs.rmSync(tmp, { force: true });
231
+ throw e;
232
+ }
233
+ }
234
+ const jsonl = (rows) => Buffer.from(rows.map((r) => JSON.stringify(r)).join("\n") + (rows.length ? "\n" : ""));
235
+ function readRows(name) {
236
+ const b = readGuardFile(name, MAX_ROWS_BYTES);
237
+ if (!b)
238
+ return [];
239
+ const out = [];
240
+ for (const line of b.toString("utf8").split("\n")) {
241
+ if (!line.trim())
242
+ continue;
243
+ try {
244
+ out.push(JSON.parse(line));
245
+ }
246
+ catch {
247
+ throw new LibraryError(`guard/${name} is damaged.`);
248
+ }
249
+ }
250
+ return out;
251
+ }
252
+ // meta.json's format. Version 1 (one shared threshold) is not loaded: an import could only weaken it, so a library
253
+ // built by that version reads as "not run" until guard setup builds it again.
254
+ export const META_VERSION = 2;
255
+ function parseMeta(b) {
256
+ let m;
257
+ try {
258
+ m = JSON.parse(b.toString("utf8"));
259
+ }
260
+ catch {
261
+ throw new LibraryError("guard/meta.json is damaged.");
262
+ }
263
+ if (m && typeof m === "object" && m.v !== META_VERSION)
264
+ throw new LibraryError("The guard library was built by an older version of Tiresias, with one alarm line for every collection. Run tiresias guard setup again to rebuild it.");
265
+ const ok = m && typeof m.model === "string" && typeof m.prefix === "string" && Number.isInteger(m.dim) && m.dim >= MIN_DIM && m.dim <= MAX_DIM &&
266
+ Number.isInteger(m.attacks?.count) && Number.isInteger(m.ordinary?.count) && m.attacks.count > 0 && m.ordinary.count > 0 &&
267
+ typeof m.attacks.sha256 === "string" && typeof m.ordinary.sha256 === "string" && typeof m.generation === "string" &&
268
+ m.lines && typeof m.lines === "object" && Array.isArray(m.segments);
269
+ if (!ok)
270
+ throw new LibraryError("guard/meta.json is damaged.");
271
+ // The segments must cover every attack row once, in order, and every collection must have a finite line.
272
+ let next = 0;
273
+ for (const s of m.segments) {
274
+ if (!Array.isArray(s) || typeof s[0] !== "string" || s[1] !== next || !Number.isInteger(s[2]) || s[2] < 1)
275
+ throw new LibraryError("guard/meta.json is damaged.");
276
+ const line = Object.hasOwn(m.lines, s[0]) ? m.lines[s[0]] : undefined;
277
+ if (!line || typeof line.threshold !== "number" || !Number.isFinite(line.threshold))
278
+ throw new LibraryError("guard/meta.json is damaged.");
279
+ next += s[2];
280
+ }
281
+ if (next !== m.attacks.count)
282
+ throw new LibraryError("guard/meta.json is damaged.");
283
+ return m;
284
+ }
285
+ // Runs of attack rows that belong to one collection, from the rows in order.
286
+ export function segmentsOf(rows) {
287
+ const out = [];
288
+ rows.forEach((r, i) => {
289
+ const last = out.at(-1);
290
+ if (last && last[0] === r.c)
291
+ last[2]++;
292
+ else
293
+ out.push([r.c, i, 1]);
294
+ });
295
+ return out;
296
+ }
297
+ const groupsOf = (segments) => {
298
+ const g = new Map();
299
+ for (const [c, start, count] of segments)
300
+ (g.get(c) ?? g.set(c, []).get(c)).push([start, count]);
301
+ return g;
302
+ };
303
+ // The library, checked whole: every size must add up and both vector files must match the fingerprints meta.json
304
+ // recorded. Every backing file is checked on each use, and any change reloads the library (a long-lived MCP
305
+ // server sees a rebuild or an import without a restart).
306
+ let cached = null;
307
+ function stampOf() {
308
+ const dir = subDir(GUARD_DIR, false);
309
+ if (!dir)
310
+ return null;
311
+ const stamps = [];
312
+ for (const name of Object.values(F)) {
313
+ let st;
314
+ try {
315
+ st = fs.lstatSync(path.join(dir, name));
316
+ }
317
+ catch {
318
+ throw new LibraryError("The guard library is incomplete.");
319
+ }
320
+ if (!st.isFile() || (process.getuid && st.uid !== process.getuid()))
321
+ throw new LibraryError(`guard/${name} is not a plain file owned by you.`);
322
+ stamps.push(`${st.dev}:${st.ino}:${st.size}:${st.mtimeMs}:${st.ctimeMs}:${st.uid}:${st.gid}:${st.mode}`);
323
+ }
324
+ return { key: dir, stamp: stamps.join(";") };
325
+ }
326
+ export function loadLibrary() {
327
+ const s = stampOf();
328
+ if (!s)
329
+ return null;
330
+ if (cached && cached.key === s.key && cached.stamp === s.stamp)
331
+ return cached.lib;
332
+ const mb = readGuardFile(F.meta, MAX_META);
333
+ if (!mb)
334
+ return null;
335
+ const meta = parseMeta(mb);
336
+ const a = readGuardFile(F.attacks, MAX_VECTORS_BYTES);
337
+ const o = readGuardFile(F.ordinary, MAX_VECTORS_BYTES);
338
+ if (!a || !o)
339
+ throw new LibraryError("The guard library is incomplete.");
340
+ if (a.length !== meta.attacks.count * meta.dim * 4 || o.length !== meta.ordinary.count * meta.dim * 4)
341
+ throw new LibraryError("The guard library's sizes do not match.");
342
+ if (fileHash(a) !== meta.attacks.sha256 || fileHash(o) !== meta.ordinary.sha256)
343
+ throw new LibraryError("The guard library's files do not match its record.");
344
+ const attackRows = readRows(F.attackRows);
345
+ const ordinaryRows = readRows(F.ordinaryRows);
346
+ const imported = readRows(F.imported);
347
+ const attackHashes = new Set(attackRows.map((r) => JSON.stringify([r.c, r.h])));
348
+ if (attackRows.length !== meta.attacks.count || ordinaryRows.length !== meta.ordinary.count ||
349
+ JSON.stringify(segmentsOf(attackRows)) !== JSON.stringify(meta.segments) ||
350
+ imported.length !== meta.attacks.count - meta.attacks.starter ||
351
+ imported.some((r) => typeof r.t !== "string" || textHash(r.t) !== r.h || !attackHashes.has(JSON.stringify([r.c, r.h]))))
352
+ throw new LibraryError("The guard library's records do not match its vectors.");
353
+ const lib = { meta, attacks: toMatrix(a), ordinary: toMatrix(o), groups: groupsOf(meta.segments) };
354
+ for (const m of [lib.attacks, lib.ordinary])
355
+ for (let i = 0; i < m.length; i++)
356
+ if (!Number.isFinite(m[i]))
357
+ throw new LibraryError("The guard library holds a number that is not finite.");
358
+ cached = { key: s.key, stamp: s.stamp, lib };
359
+ return lib;
360
+ }
361
+ export const forgetLibrary = () => {
362
+ cached = null;
363
+ };
364
+ // The highest cosine to one collection (all its runs of rows).
365
+ const maxIn = (v, attacks, dim, runs, skip) => {
366
+ let best = -Infinity;
367
+ for (const [start, count] of runs)
368
+ best = Math.max(best, maxDot(v, attacks, dim, skip, start, count));
369
+ return best;
370
+ };
371
+ // A text is marked when, for ANY collection, (highest cosine to that collection) minus (highest cosine to ordinary
372
+ // text) is above that collection's own line. So a collection only ever adds marks: an import can never move the
373
+ // starter's line or take a mark away from it.
374
+ export function marked(v, lib) {
375
+ const b = maxDot(v, lib.ordinary, lib.meta.dim);
376
+ for (const [c, runs] of lib.groups)
377
+ if (maxIn(v, lib.attacks, lib.meta.dim, runs) - b > lib.meta.lines[c].threshold)
378
+ return true;
379
+ return false;
380
+ }
381
+ // ---- calibration ----
382
+ // Every collection gets its own alarm line, set on ordinary text so that about `rate` percent of ordinary passages
383
+ // score above it. Two things keep the line steady:
384
+ // - Two folds, split by PAGE (two passages of one page are alike, so a passage scored against its own page's other
385
+ // passages would look safer than it is): each half's passages are scored against the other half as the ordinary
386
+ // library, and the scores of both halves are pooled, so every passage counts once.
387
+ // - At most CAL_PER_PAGE passages of one page (the first ones gathered) count when the line is set, so one page
388
+ // full of instructions (a tutorial, say) cannot set the line on its own. Resampling the pages moved the
389
+ // starter's 1% line between 0.024 and 0.042 with 40 passages a page, and between 0.0195 and 0.0235 with 12.
390
+ // Every gathered passage is still in the ordinary library at read time, where a passage meets more ordinary text
391
+ // than it did here, so the lines are slightly conservative (a little under the target rate of false alarms).
392
+ export const CAL_PER_PAGE = 12;
393
+ export const half = (page) => createHash("sha256").update(page).digest()[0] & 1;
394
+ // The rows that count for the lines: the first CAL_PER_PAGE of each page, in the order gathered.
395
+ export function calibrationRows(pages) {
396
+ const seen = new Map();
397
+ const out = [];
398
+ pages.forEach((p, i) => {
399
+ const n = seen.get(p) ?? 0;
400
+ if (n < CAL_PER_PAGE)
401
+ out.push(i);
402
+ seen.set(p, n + 1);
403
+ });
404
+ return out;
405
+ }
406
+ // Each calibration passage's score against every collection, with the other fold as the ordinary library.
407
+ export function calScores(attacks, groups, ordinary, pages, dim) {
408
+ let side = pages.map(half);
409
+ // A tiny library could put every page on one side; then the pages alternate instead.
410
+ if (side.every((s) => s === side[0])) {
411
+ const order = [...new Set(pages)];
412
+ side = pages.map((p) => order.indexOf(p) % 2);
413
+ }
414
+ const fold = [0, 1].map((h) => {
415
+ const idx = pages.map((_, i) => i).filter((i) => side[i] === h);
416
+ const m = new Float32Array(idx.length * dim);
417
+ idx.forEach((r, k) => m.set(ordinary.subarray(r * dim, (r + 1) * dim), k * dim));
418
+ return m;
419
+ });
420
+ const rows = calibrationRows(pages);
421
+ const scores = new Map([...groups.keys()].map((c) => [c, new Float64Array(rows.length)]));
422
+ rows.forEach((r, k) => {
423
+ const v = ordinary.subarray(r * dim, (r + 1) * dim);
424
+ const b = maxDot(v, fold[1 - side[r]], dim);
425
+ for (const [c, runs] of groups)
426
+ scores.get(c)[k] = maxIn(v, attacks, dim, runs) - b;
427
+ });
428
+ return { rows, scores };
429
+ }
430
+ // The line that marks `rate` percent of the pooled scores (the k-th highest, so k - 1 score above it).
431
+ export function lineFor(scores, rate) {
432
+ const k = Math.floor((scores.length * rate) / 100);
433
+ if (k < MIN_ABOVE_LINE)
434
+ throw new ConfigError(tooFew(scores.length, rate));
435
+ const sorted = Array.from(scores).sort((x, y) => y - x);
436
+ const threshold = sorted[k - 1];
437
+ return { threshold, marked: Array.from(scores).filter((s) => s > threshold).length };
438
+ }
439
+ const tooFew = (n, rate) => `Too few ordinary passages to calibrate at ${rate}% false alarms: ${n} count for the lines (at most ${CAL_PER_PAGE} from each page), and it needs at least ${Math.ceil((MIN_ABOVE_LINE * 100) / rate)}. Gather more ordinary text (more pages with --ordinary-urls, or a larger --ordinary file), or allow a higher --false-alarms.`;
440
+ // The owner's own numbers for their model. The starter: of its texts, how many it still marks at its own line when
441
+ // their whole kind of trick is left out (a trick it has never seen). Each imported collection: how many starter
442
+ // texts it marks on its own at its own line, which says whether it knows tricks planted in pages at all.
443
+ export function selfTest(lib, rows) {
444
+ let caught = 0;
445
+ let n = 0;
446
+ const per = {};
447
+ const counts = new Map();
448
+ const starterRuns = lib.groups.get("starter") ?? [];
449
+ for (let r = 0; r < rows.length; r++) {
450
+ if (rows[r].c !== "starter")
451
+ continue;
452
+ n++;
453
+ const kind = rows[r].k;
454
+ const v = lib.attacks.subarray(r * lib.dim, (r + 1) * lib.dim);
455
+ const b = maxDot(v, lib.ordinary, lib.dim);
456
+ if (maxIn(v, lib.attacks, lib.dim, starterRuns, (x) => rows[x].k === kind) - b > lib.lines.starter.threshold)
457
+ caught++;
458
+ for (const [c, runs] of lib.groups)
459
+ if (c !== "starter" && maxIn(v, lib.attacks, lib.dim, runs) - b > lib.lines[c].threshold)
460
+ counts.set(c, (counts.get(c) ?? 0) + 1);
461
+ }
462
+ for (const c of lib.groups.keys())
463
+ if (c !== "starter")
464
+ per[c] = { starter_marked: counts.get(c) ?? 0, adds_little: (counts.get(c) ?? 0) < n * IMPORT_FLOOR };
465
+ return { unseen_caught: caught, starter: n, floor: SELF_TEST_FLOOR, weak: n > 0 && caught < n * SELF_TEST_FLOOR, collections: per, import_floor: IMPORT_FLOOR };
466
+ }
467
+ // The lines, what each marks among the calibration passages, the honest total, and the self-test, in words.
468
+ export function libraryText(m) {
469
+ const cal = m.calibration;
470
+ const lines = Object.entries(m.lines).map(([c, l]) => `${c} ${l.threshold.toFixed(4)} (marks ${l.marked} of ${cal.passages})`).join(", ");
471
+ const t = m.self_test;
472
+ const imports = Object.entries(t.collections).map(([c, x]) => x.adds_little
473
+ ? ` The collection "${c}" adds little for text planted in pages: on its own it marks ${x.starter_marked} of ${t.starter} starter texts, and it still adds false alarms.`
474
+ : ` On its own the collection "${c}" marks ${x.starter_marked} of ${t.starter} starter texts.`).join("");
475
+ return `Alarm lines, one per collection, each set for ${m.false_alarms}% false alarms on ${cal.passages} ordinary calibration passages (at most ${cal.per_page} a page): ${lines}. Marked by any collection: ${cal.any_marked} of ${cal.passages}.` +
476
+ ` Self-test: the starter marks ${t.unseen_caught} of ${t.starter} of its own texts when their kind of trick is left out (a trick it has never seen).` +
477
+ (t.weak ? ` That is under ${Math.round(t.floor * 100)}% of them: this embedding model separates planted instructions from ordinary text poorly, so the check will add little.` : "") +
478
+ imports;
479
+ }
480
+ const pageKey = (s) => createHash("sha256").update(s).digest("hex").slice(0, 16);
481
+ const say = (line) => process.stderr.write(`guard: ${line}\n`);
482
+ function readOwnerFile(file, max, what) {
483
+ let fd;
484
+ try {
485
+ let st;
486
+ try {
487
+ fd = fs.openSync(file, fs.constants.O_RDONLY | NONBLOCK);
488
+ st = fs.fstatSync(fd);
489
+ }
490
+ catch {
491
+ throw new ConfigError(`${what}: ${file} does not exist.`);
492
+ }
493
+ if (!st.isFile())
494
+ throw new ConfigError(`${what}: ${file} is not a file.`);
495
+ if (st.size > max)
496
+ throw new ConfigError(`${what}: ${file} is larger than ${Math.round(max / 1024 / 1024)} MB.`);
497
+ return fs.readFileSync(fd, "utf8");
498
+ }
499
+ finally {
500
+ if (fd !== undefined)
501
+ fs.closeSync(fd);
502
+ }
503
+ }
504
+ // The owner's own passages: one JSON object per line with "text", and "page" or "url" to group them by page.
505
+ // Without either, every 10 consecutive passages count as one page.
506
+ export function ordinaryFromFile(file) {
507
+ const passages = [];
508
+ const seen = new Set();
509
+ let skipped = 0;
510
+ let n = 0;
511
+ for (const [i, line] of readOwnerFile(file, MAX_IMPORT_BYTES, "--ordinary").split("\n").entries()) {
512
+ if (!line.trim())
513
+ continue;
514
+ let o;
515
+ try {
516
+ o = JSON.parse(line);
517
+ }
518
+ catch {
519
+ throw new ConfigError(`--ordinary: line ${i + 1} is not JSON. The file takes one {"text": "...", "page": "..."} object per line.`);
520
+ }
521
+ const r = o;
522
+ if (!o || typeof o !== "object" || typeof r.text !== "string")
523
+ throw new ConfigError(`--ordinary: line ${i + 1} has no "text". The file takes one {"text": "...", "page": "..."} object per line.`);
524
+ const text = r.text.trim().slice(0, MAX_PASSAGE);
525
+ const h = textHash(text);
526
+ if (text.length < MIN_PASSAGE || seen.has(h) || passages.length >= MAX_ORDINARY) {
527
+ skipped++;
528
+ continue;
529
+ }
530
+ seen.add(h);
531
+ const group = typeof r.page === "string" || typeof r.page === "number" ? String(r.page) : typeof r.url === "string" ? r.url : `block-${Math.floor(n / 10)}`;
532
+ n++;
533
+ passages.push({ text, page: pageKey(group) });
534
+ }
535
+ return { passages, skipped };
536
+ }
537
+ export function readUrlList(file) {
538
+ const urls = [];
539
+ for (const line of readOwnerFile(file, 1024 * 1024, "--ordinary-urls").split("\n")) {
540
+ const u = line.trim();
541
+ if (!u || u.startsWith("#"))
542
+ continue;
543
+ if (!/^https?:\/\//i.test(u))
544
+ throw new ConfigError("--ordinary-urls: every line must be an http or https address (lines starting with # are comments).");
545
+ if (urls.length >= MAX_URLS)
546
+ break;
547
+ if (!urls.includes(u))
548
+ urls.push(u);
549
+ }
550
+ return urls;
551
+ }
552
+ // v1.2 (F.1): only our fixed codes and words belong in setup's diagnostics, never a page's error body.
553
+ function ordinaryFailure(e) {
554
+ if (e.status === "ok" || e.status === "unchanged")
555
+ return "no text";
556
+ if (e.status === "wall") {
557
+ const code = e.handoff?.reason;
558
+ return `wall: ${code && ["bot_challenge", "captcha", "login_required", "forbidden", "owner_hand_off"].includes(code) ? code : "unreadable"}`;
559
+ }
560
+ if (e.status === "error") {
561
+ if (/^No section [1-9][0-9]*\. This page has 0 sections\.$/.test(e.message ?? ""))
562
+ return "no text";
563
+ const http = /^The site answered HTTP ([1-5][0-9]{2})\.$/.exec(e.message ?? "");
564
+ return http ? `error: HTTP ${http[1]}` : e.message === "The site took too long to answer." ? "error: timeout" : "error: unreadable";
565
+ }
566
+ if (e.status === "refused")
567
+ return e.message?.includes("robots.txt") ? "refused: robots.txt" : "refused: not allowed";
568
+ if (e.status === "payment_required")
569
+ return "payment_required";
570
+ if (e.status === "flagged")
571
+ return "flagged";
572
+ return "file_warning";
573
+ }
574
+ // Ordinary pages read through Tiresias's own engine, the normal honest way: robots.txt, waits, spacing, the cache
575
+ // and walls all apply, and the reads are in history like any other. The first few sections of each page give its
576
+ // passages. A page that fails is skipped and counted.
577
+ export async function ordinaryFromUrls(urls, agent = "tiresias-guard-setup") {
578
+ const engine = await import("./engine.js");
579
+ const passages = [];
580
+ const seen = new Set();
581
+ let failed = 0;
582
+ const failures = [];
583
+ for (const [i, url] of urls.entries()) {
584
+ if (passages.length >= MAX_ORDINARY)
585
+ break;
586
+ const page = pageKey(url);
587
+ let got = 0;
588
+ let reason = "no text";
589
+ for (let s = 1; s <= SECTIONS_PER_PAGE && got < MAX_PER_PAGE; s++) {
590
+ let e;
591
+ try {
592
+ e = await engine.read(url, { section: s, page: 1 }, { agent });
593
+ }
594
+ catch {
595
+ reason = "error: unreadable";
596
+ break;
597
+ }
598
+ if (e.status !== "ok" && e.status !== "unchanged") {
599
+ reason = ordinaryFailure(e);
600
+ break;
601
+ }
602
+ const text = e.untrusted_content?.section?.text;
603
+ if (typeof text !== "string")
604
+ break;
605
+ for (const para of text.split("\n\n")) {
606
+ const t = para.trim().slice(0, MAX_PASSAGE);
607
+ const h = textHash(t);
608
+ if (t.length < MIN_PASSAGE || seen.has(h))
609
+ continue;
610
+ seen.add(h);
611
+ passages.push({ text: t, page });
612
+ if (++got >= MAX_PER_PAGE || passages.length >= MAX_ORDINARY)
613
+ break;
614
+ }
615
+ }
616
+ if (!got) {
617
+ failed++;
618
+ failures.push({ url, reason });
619
+ }
620
+ say(`page ${i + 1} of ${urls.length}: ${url}: ${got ? `${got} passages` : `skipped (${reason})`}`);
621
+ }
622
+ return { passages, tried: urls.length, failed, failures };
623
+ }
624
+ // ---- the owner's commands (CLI only) ----
625
+ const PRIVATE = "Private mode: the meaning check is not changed, because a private session changes nothing.";
626
+ const NAME_RE = /^[a-z0-9-]{1,32}$/;
627
+ export function parseFalseAlarms(v) {
628
+ if (v === undefined)
629
+ return DEFAULT_FALSE_ALARMS;
630
+ const n = /^\d{1,2}(\.\d{1,2})?$/.test(v) ? Number(v) : NaN;
631
+ if (!(n >= 0.1 && n <= 5))
632
+ throw new ConfigError("--false-alarms takes a percent from 0.1 to 5, like 1 or 0.5. The default is 1.");
633
+ return n;
634
+ }
635
+ function parseTimeout(v) {
636
+ if (v === undefined)
637
+ return GUARD_TIMEOUT;
638
+ const n = /^\d{1,2}$/.test(v) ? Number(v) : NaN;
639
+ if (!(n >= 1 && n <= 60))
640
+ throw new ConfigError("--timeout takes whole seconds from 1 to 60. The default is 4.");
641
+ return n;
642
+ }
643
+ function embedFailed(e, when) {
644
+ if (e instanceof EmbedError)
645
+ throw new ConfigError(`${when}: ${e.message} Check that the embedding model is loaded and that --url and --model are right.`);
646
+ throw e;
647
+ }
648
+ // What setup needs before any page is read: the setting, and whether the address needs the typed confirmation.
649
+ async function plan(o) {
650
+ if (o.url === undefined || o.model === undefined)
651
+ throw new ConfigError("Usage: tiresias guard setup --url http://localhost:1234/v1 --model <embedding model id> [--prefix \"...\"] [--false-alarms 1] [--ordinary <file.jsonl> | --ordinary-urls <file.txt>] [--timeout 4]");
652
+ if (o.ordinary !== undefined && o.ordinaryUrls !== undefined)
653
+ throw new ConfigError("Use --ordinary or --ordinary-urls, not both.");
654
+ const url = parseGuardUrl(o.url, isOwnerAddress);
655
+ const model = o.model.trim();
656
+ if (!model || model.length > 200 || /[\u0000-\u001f\u007f]/.test(model))
657
+ throw new ConfigError("--model takes the embedding model's id, as your server lists it.");
658
+ const prefix = o.prefix ?? defaultPrefix(model);
659
+ if (prefix.length > 200 || /[\u0000-\u001f\u007f]/.test(prefix))
660
+ throw new ConfigError("--prefix takes at most 200 characters, with no control characters.");
661
+ const timeout_seconds = parseTimeout(o.timeout);
662
+ const again = `tiresias guard setup --url ${sq(url)} --model ${sq(model)}${o.prefix !== undefined ? ` --prefix ${sq(prefix)}` : ""}`;
663
+ let where;
664
+ try {
665
+ where = await classify(url);
666
+ }
667
+ catch (e) {
668
+ return embedFailed(e, "The endpoint's address");
669
+ }
670
+ const cfg = { url, model, prefix, timeout_seconds };
671
+ if (where === "public") {
672
+ if (new URL(url).protocol !== "https:")
673
+ throw new ConfigError("Plain http to an address outside your network is refused: page text would cross the internet unencrypted. Use https, or an address on your own network.");
674
+ // Checked here, before any page is read, so a missing phrase never costs a long gather; confirmedWrite checks it
675
+ // again (against the confirmed state) when the setting is written.
676
+ if (asking() && o.confirm !== GUARD_PHRASE && !alreadyPublic(url))
677
+ throw new ConfigError(`${refusal(GUARD_PHRASE, again)} Why: ${url} is not on this machine or your network, so every passage a local read checks would be sent there.`);
678
+ cfg.allow_public = true;
679
+ }
680
+ return { cfg, again };
681
+ }
682
+ function alreadyPublic(url) {
683
+ try {
684
+ const g = loadGuard();
685
+ return !!g && g.allow_public === true && g.url === url;
686
+ }
687
+ catch {
688
+ return false;
689
+ }
690
+ }
691
+ // guard setup: build (or rebuild) the libraries, calibrate, self-test, then write the setting.
692
+ export async function setup(o, priv = sessionPrivate()) {
693
+ if (priv)
694
+ throw new ConfigError(PRIVATE);
695
+ const failedPages = [];
696
+ try {
697
+ const started = Date.now();
698
+ const rate = parseFalseAlarms(o.falseAlarms);
699
+ const initial = withGuardLock(() => ({ state: guardState(), imported: safeImported() }));
700
+ const { cfg, again } = await plan(o);
701
+ // A first call tells us the model works and its dimension, before any page is read.
702
+ let dim;
703
+ try {
704
+ dim = (await embed(cfg, [cfg.prefix + "A short test sentence about the weather."], { timeoutMs: SETUP_TIMEOUT_MS }))[0].length;
705
+ }
706
+ catch (e) {
707
+ return embedFailed(e, "The first call to the endpoint");
708
+ }
709
+ // The attack library: the starter set, plus every collection the owner imported before (kept across rebuilds).
710
+ const start = starter();
711
+ const imported = initial.imported;
712
+ vectorBudget(dim, start.length + imported.length, 0);
713
+ // The ordinary library.
714
+ let ordinary;
715
+ let source = "urls";
716
+ let tried;
717
+ let failed;
718
+ if (o.ordinary !== undefined) {
719
+ source = "file";
720
+ const r = ordinaryFromFile(o.ordinary);
721
+ ordinary = r.passages;
722
+ say(`${ordinary.length} ordinary passages from ${o.ordinary}${r.skipped ? ` (${r.skipped} skipped: short, repeated or over ${MAX_ORDINARY})` : ""}`);
723
+ }
724
+ else {
725
+ const urls = readUrlList(o.ordinaryUrls ?? bundledUrlList());
726
+ say(`reading ${urls.length} ordinary pages through Tiresias (robots.txt, waits and walls apply as usual)`);
727
+ const r = await ordinaryFromUrls(urls);
728
+ ordinary = r.passages;
729
+ tried = r.tried;
730
+ failed = r.failed;
731
+ failedPages.push(...r.failures);
732
+ say(`${ordinary.length} ordinary passages from ${r.tried - r.failed} pages; ${r.failed} pages skipped`);
733
+ }
734
+ const pages = new Set(ordinary.map((p) => p.page)).size;
735
+ vectorBudget(dim, start.length + imported.length, ordinary.length);
736
+ if (ordinary.length < MIN_ORDINARY || pages < MIN_ORDINARY_PAGES)
737
+ throw new ConfigError(`Not enough ordinary text to calibrate: ${ordinary.length} passages from ${pages} pages, and setup needs at least ${MIN_ORDINARY} passages from at least ${MIN_ORDINARY_PAGES} pages. Nothing was changed.`);
738
+ const counted = calibrationRows(ordinary.map((p) => p.page)).length;
739
+ if (Math.floor((counted * rate) / 100) < MIN_ABOVE_LINE)
740
+ throw new ConfigError(`${tooFew(counted, rate)} Nothing was changed.`);
741
+ // Embed: attacks first, then ordinary text, in batches, with progress on standard error.
742
+ const attackTexts = [...start.map((s) => s.text), ...imported.map((r) => r.t)];
743
+ const rows = [...start.map((s) => ({ c: "starter", k: s.kind, h: textHash(s.text) })), ...imported.map((r) => ({ c: r.c, k: null, h: r.h }))];
744
+ rowBudget(F.attackRows, rows);
745
+ rowBudget(F.ordinaryRows, ordinary.map(p => ({ p: p.page, h: textHash(p.text) })));
746
+ rowBudget(F.imported, imported);
747
+ let av;
748
+ let ov;
749
+ try {
750
+ say(`embedding ${attackTexts.length} attack texts`);
751
+ av = await embedAll(cfg, attackTexts.map((t) => cfg.prefix + t), { timeoutMs: SETUP_TIMEOUT_MS, dim, progress: progress(attackTexts.length) });
752
+ say(`embedding ${ordinary.length} ordinary passages`);
753
+ ov = await embedAll(cfg, ordinary.map((p) => cfg.prefix + p.text), { timeoutMs: SETUP_TIMEOUT_MS, dim, progress: progress(ordinary.length) });
754
+ }
755
+ catch (e) {
756
+ return embedFailed(e, "Embedding the libraries");
757
+ }
758
+ const attacks = toBuffer(av, dim);
759
+ const ord = toBuffer(ov, dim);
760
+ const now = new Date().toISOString();
761
+ const meta = build(cfg, dim, rate, rows, toMatrix(attacks), toMatrix(ord), ordinary.map((p) => p.page), { built_at: now, source, pages, tried, failed });
762
+ withGuardLock(() => {
763
+ unchangedGuard(initial.state);
764
+ // v1.2: confirmedWrite holds the config lock before any library file is replaced.
765
+ confirmedWrite({ name: "guard" }, (x) => void (x.guard = cfg), () => {
766
+ unchangedGuard(initial.state);
767
+ advanceGuard();
768
+ writeLibrary(meta, attacks, rows, ord, ordinary.map((p) => ({ p: p.page, h: textHash(p.text) })), imported);
769
+ }, { confirm: o.confirm, again });
770
+ forgetLibrary();
771
+ });
772
+ const lib = showLibrary(meta);
773
+ return { status: "ok", message: `The meaning check is set up: ${meta.attacks.count} attack texts, ${meta.ordinary.count} ordinary passages from ${pages} pages. ${libraryText(meta)} It runs on local model mode's reads (tiresias mcp --local, tiresias read --local).`, guard: cfg, library: lib, seconds: Math.round((Date.now() - started) / 1000) };
774
+ }
775
+ finally {
776
+ if (failedPages.length)
777
+ say(`failed pages: ${failedPages.map((p) => `${p.url} (${p.reason})`).join(", ")}`);
778
+ }
779
+ }
780
+ const progress = (total) => {
781
+ let last = 0;
782
+ return (done) => {
783
+ if (done === total || done - last >= 256) {
784
+ last = done;
785
+ say(` ${done} of ${total}`);
786
+ }
787
+ };
788
+ };
789
+ // Lines and self-test for these libraries, as meta.json records them. `keep` holds lines to leave as they are: an
790
+ // import sets the new collection's line, and leaves the others alone (the ordinary library is the same).
791
+ function build(cfg, dim, rate, rows, attacks, ordinary, pages, g, keep = {}) {
792
+ if (rows.filter((r) => r.c === "starter").length < MIN_ATTACKS)
793
+ throw new ConfigError(`The starter library has fewer than ${MIN_ATTACKS} texts.`);
794
+ const segments = segmentsOf(rows);
795
+ const groups = groupsOf(segments);
796
+ const cal = calScores(attacks, groups, ordinary, pages, dim);
797
+ const lines = {};
798
+ for (const [c, sc] of cal.scores) {
799
+ const kept = Object.hasOwn(keep, c) ? keep[c] : undefined;
800
+ lines[c] = kept ? { threshold: kept.threshold, marked: Array.from(sc).filter((x) => x > kept.threshold).length } : lineFor(sc, rate);
801
+ }
802
+ let any = 0;
803
+ for (let k = 0; k < cal.rows.length; k++)
804
+ if ([...cal.scores].some(([c, sc]) => sc[k] > lines[c].threshold))
805
+ any++;
806
+ const self = selfTest({ attacks, ordinary, dim, lines, groups }, rows);
807
+ const collections = {};
808
+ for (const r of rows)
809
+ if (r.c !== "starter")
810
+ collections[r.c] = (collections[r.c] ?? 0) + 1;
811
+ return {
812
+ v: META_VERSION,
813
+ generation: randomBytes(8).toString("hex"),
814
+ built_at: g.built_at,
815
+ updated_at: new Date().toISOString(),
816
+ model: cfg.model,
817
+ prefix: cfg.prefix,
818
+ dim,
819
+ false_alarms: rate,
820
+ lines,
821
+ segments,
822
+ calibration: { passages: cal.rows.length, pages: new Set(pages).size, per_page: CAL_PER_PAGE, any_marked: any },
823
+ attacks: { count: rows.length, sha256: fileHash(Buffer.from(attacks.buffer, attacks.byteOffset, attacks.byteLength)), starter: rows.filter((r) => r.c === "starter").length, collections },
824
+ ordinary: { count: pages.length, sha256: fileHash(Buffer.from(ordinary.buffer, ordinary.byteOffset, ordinary.byteLength)), pages: g.pages, source: g.source, ...(g.tried !== undefined ? { pages_tried: g.tried, pages_failed: g.failed } : {}) },
825
+ self_test: self,
826
+ };
827
+ }
828
+ function fileBudget(name, bytes, max) {
829
+ if (bytes > max)
830
+ throw new ConfigError(`guard/${name} would need ${bytes} bytes; the limit is ${max} bytes. Nothing was changed.`);
831
+ }
832
+ // v1.2: count exactly the JSONL the reader will load, before embedding or replacing any library file.
833
+ function rowBudget(name, rows) {
834
+ let bytes = 0;
835
+ for (const row of rows)
836
+ bytes += Buffer.byteLength(JSON.stringify(row)) + 1;
837
+ fileBudget(name, bytes, MAX_ROWS_BYTES);
838
+ }
839
+ // Every file first, meta.json last: a reader in between treats a fingerprint mismatch as not run.
840
+ function writeLibrary(meta, attacks, rows, ordinary, ordRows, imported) {
841
+ const files = [
842
+ [F.attacks, attacks, MAX_VECTORS_BYTES], [F.attackRows, jsonl(rows), MAX_ROWS_BYTES],
843
+ [F.imported, jsonl(imported), MAX_ROWS_BYTES],
844
+ ...(ordinary ? [[F.ordinary, ordinary, MAX_VECTORS_BYTES]] : []),
845
+ ...(ordRows ? [[F.ordinaryRows, jsonl(ordRows), MAX_ROWS_BYTES]] : []),
846
+ [F.meta, Buffer.from(JSON.stringify(meta, null, 1) + "\n"), MAX_META],
847
+ ];
848
+ for (const [name, data, max] of files)
849
+ fileBudget(name, data.length, max);
850
+ for (const [name, data] of files)
851
+ writeGuardFile(name, data);
852
+ }
853
+ function safeImported() {
854
+ try {
855
+ const rows = readRows(F.imported);
856
+ if (rows.some((r) => !r || typeof r.t !== "string" || typeof r.c !== "string" || typeof r.h !== "string"))
857
+ throw new Error("invalid imported row");
858
+ return rows;
859
+ }
860
+ catch {
861
+ throw new ConfigError(`guard/${F.imported} cannot be read or has an invalid line. Nothing was changed.`);
862
+ }
863
+ }
864
+ export async function importFile(file, name, priv = sessionPrivate()) {
865
+ if (priv)
866
+ throw new ConfigError(PRIVATE);
867
+ const initial = withGuardLock(() => {
868
+ const cfg = loadGuard(isOwnerAddress);
869
+ if (!cfg)
870
+ throw new ConfigError("The meaning check is not set up. Run tiresias guard setup first.");
871
+ const imported = safeImported();
872
+ return { cfg, lib: loadLibraryOrFail(), state: guardState(), rows: readRows(F.attackRows), ordRows: readRows(F.ordinaryRows), imported };
873
+ });
874
+ const { cfg, lib, rows, ordRows } = initial;
875
+ if (lib.meta.model !== cfg.model || lib.meta.prefix !== cfg.prefix)
876
+ throw new ConfigError("The library was built for another model or prefix than the setting names. Run tiresias guard setup again first.");
877
+ const base = path.basename(file).replace(/\.[^.]*$/, "").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32);
878
+ let collection = name ?? (base || "import");
879
+ if (name === undefined) {
880
+ for (let n = 2; collection === "starter" || Object.hasOwn(lib.meta.lines, collection); n++) {
881
+ const suffix = `-${n}`;
882
+ collection = (base || "import").slice(0, 32 - suffix.length) + suffix;
883
+ }
884
+ }
885
+ if (!NAME_RE.test(collection) || collection === "starter")
886
+ throw new ConfigError('--name takes 1 to 32 of a-z, 0-9 and "-" (not "starter").');
887
+ if (Object.hasOwn(lib.meta.lines, collection))
888
+ throw new ConfigError("That collection name already exists. Pick another name with --name.");
889
+ const raw = readOwnerFile(file, MAX_IMPORT_BYTES, "guard import");
890
+ const asJson = /\.jsonl?$/i.test(file);
891
+ const texts = [];
892
+ for (const [i, line] of raw.split("\n").entries()) {
893
+ if (!line.trim())
894
+ continue;
895
+ if (!asJson) {
896
+ texts.push(line.trim());
897
+ continue;
898
+ }
899
+ let o;
900
+ try {
901
+ o = JSON.parse(line);
902
+ }
903
+ catch {
904
+ throw new ConfigError(`guard import: line ${i + 1} of the file is not JSON. A .jsonl file takes one {"text": "..."} object per line; any other file is read as plain text, one text per line. Nothing was imported.`);
905
+ }
906
+ if (!o || typeof o !== "object" || Array.isArray(o) || typeof o.text !== "string")
907
+ throw new ConfigError(`guard import: line ${i + 1} of the file has no "text". Nothing was imported.`);
908
+ texts.push(o.text.trim());
909
+ }
910
+ if (rows.length !== lib.meta.attacks.count)
911
+ throw new LibraryError("The guard library's records do not match its vectors. Run tiresias guard setup again.");
912
+ const have = new Set(rows.map((r) => r.h));
913
+ const skipped = { duplicate: 0, too_short: 0, too_long: 0, over_limit: 0 };
914
+ const fresh = [];
915
+ for (const t of texts) {
916
+ if (t.length < MIN_TEXT)
917
+ skipped.too_short++;
918
+ else if (t.length > MAX_TEXT)
919
+ skipped.too_long++;
920
+ else {
921
+ const h = textHash(t);
922
+ if (have.has(h))
923
+ skipped.duplicate++;
924
+ else if (fresh.length >= MAX_IMPORT || rows.length + fresh.length >= MAX_ATTACKS)
925
+ skipped.over_limit++;
926
+ else {
927
+ have.add(h);
928
+ fresh.push({ t, h });
929
+ }
930
+ }
931
+ }
932
+ if (ordRows.length !== lib.meta.ordinary.count)
933
+ throw new LibraryError("The guard library's records do not match its vectors. Run tiresias guard setup again.");
934
+ vectorBudget(lib.meta.dim, rows.length + fresh.length, ordRows.length);
935
+ const allRows = [...rows, ...fresh.map((f) => ({ c: collection, k: null, h: f.h }))];
936
+ const imported = [...initial.imported, ...fresh.map((f) => ({ c: collection, h: f.h, t: f.t }))];
937
+ rowBudget(F.attackRows, allRows);
938
+ rowBudget(F.ordinaryRows, ordRows);
939
+ rowBudget(F.imported, imported);
940
+ let meta = lib.meta;
941
+ if (fresh.length) {
942
+ say(`embedding ${fresh.length} new texts`);
943
+ let nv;
944
+ try {
945
+ nv = await embedAll(cfg, fresh.map((f) => cfg.prefix + f.t), { timeoutMs: SETUP_TIMEOUT_MS, dim: lib.meta.dim, progress: progress(fresh.length) });
946
+ }
947
+ catch (e) {
948
+ return embedFailed(e, "Embedding the new texts");
949
+ }
950
+ const attacks = Buffer.concat([Buffer.from(lib.attacks.buffer, lib.attacks.byteOffset, lib.attacks.byteLength), toBuffer(nv, lib.meta.dim)]);
951
+ meta = build(cfg, lib.meta.dim, lib.meta.false_alarms, allRows, toMatrix(attacks), lib.ordinary, ordRows.map((r) => r.p), {
952
+ built_at: lib.meta.built_at, source: lib.meta.ordinary.source, pages: lib.meta.ordinary.pages, tried: lib.meta.ordinary.pages_tried, failed: lib.meta.ordinary.pages_failed,
953
+ }, lib.meta.lines);
954
+ withGuardLock(() => {
955
+ unchangedGuard(initial.state);
956
+ advanceGuard();
957
+ writeLibrary(meta, attacks, allRows, null, null, imported);
958
+ forgetLibrary();
959
+ });
960
+ }
961
+ const s = Object.values(skipped).reduce((a, b) => a + b, 0);
962
+ return {
963
+ status: "ok",
964
+ message: `Imported ${fresh.length} texts into the collection "${collection}"${s ? `, skipped ${s} (${skipped.duplicate} already in the library, ${skipped.too_short} under ${MIN_TEXT} characters, ${skipped.too_long} over ${MAX_TEXT}, ${skipped.over_limit} over the limit)` : ""}.${fresh.length ? ` Its own alarm line is set; the other collections keep theirs. ${libraryText(meta)}` : ""}`,
965
+ collection,
966
+ added: fresh.length,
967
+ skipped,
968
+ library: showLibrary(meta),
969
+ };
970
+ }
971
+ function loadLibraryOrFail() {
972
+ let lib;
973
+ try {
974
+ lib = loadLibrary();
975
+ }
976
+ catch (e) {
977
+ throw new ConfigError(`${e.message} Run tiresias guard setup again to rebuild it.`);
978
+ }
979
+ if (!lib)
980
+ throw new ConfigError("The meaning check has no library. Run tiresias guard setup.");
981
+ return lib;
982
+ }
983
+ const showLibrary = (m) => ({
984
+ built_at: m.built_at,
985
+ updated_at: m.updated_at,
986
+ model: m.model,
987
+ prefix: m.prefix,
988
+ dimension: m.dim,
989
+ false_alarms_percent: m.false_alarms,
990
+ lines: m.lines,
991
+ calibration: m.calibration,
992
+ attacks: { total: m.attacks.count, starter: m.attacks.starter, collections: m.attacks.collections },
993
+ ordinary: { passages: m.ordinary.count, pages: m.ordinary.pages, from: m.ordinary.source, ...(m.ordinary.pages_tried !== undefined ? { pages_tried: m.ordinary.pages_tried, pages_failed: m.ordinary.pages_failed } : {}) },
994
+ self_test: m.self_test,
995
+ });
996
+ export function show() {
997
+ let cfg = null;
998
+ let problem;
999
+ try {
1000
+ cfg = loadGuard(isOwnerAddress);
1001
+ }
1002
+ catch (e) {
1003
+ problem = e.message;
1004
+ }
1005
+ let lib = null;
1006
+ try {
1007
+ lib = loadLibrary();
1008
+ }
1009
+ catch (e) {
1010
+ problem = `${e.message} Run tiresias guard setup again.`;
1011
+ }
1012
+ if (!problem && cfg && lib && (lib.meta.model !== cfg.model || lib.meta.prefix !== cfg.prefix))
1013
+ problem = "The library was built for another model or prefix than the setting names, so the check does not run. Run tiresias guard setup again.";
1014
+ if (!problem && cfg && !lib)
1015
+ problem = "The setting is there but the library is not, so the check does not run. Run tiresias guard setup again.";
1016
+ const library = lib ? showLibrary(lib.meta) : null;
1017
+ const message = !cfg && !lib
1018
+ ? "The meaning check is not set up. Tiresias includes no model; set up your own with: tiresias guard setup --url http://localhost:1234/v1 --model <embedding model id>"
1019
+ : `${cfg ? `Meaning check: ${cfg.model} at ${cfg.url}${cfg.allow_public ? " (outside your network, confirmed)" : ""}, ${cfg.timeout_seconds} s per local read.` : "No guard setting (the library is still there)."}${library ? ` Library: ${library.attacks.total} attack texts (${library.attacks.starter} starter${Object.keys(library.attacks.collections).length ? `, ${Object.entries(library.attacks.collections).map(([k, n]) => `${n} ${k}`).join(", ")}` : ""}), ${library.ordinary.passages} ordinary passages from ${library.ordinary.pages} pages, built ${library.built_at}. ${libraryText(lib.meta)}` : ""}${problem ? ` Problem: ${problem}` : ""}`;
1020
+ return { status: "ok", message, guard: cfg, library, ...(problem ? { problem } : {}) };
1021
+ }
1022
+ // guard check: score one text the owner gives. It prints whether it is marked, its score against each collection
1023
+ // with that collection's line, and the collection and kind of the nearest library text, never that text.
1024
+ export async function check(text) {
1025
+ const cfg = loadGuard(isOwnerAddress);
1026
+ if (!cfg)
1027
+ throw new ConfigError("The meaning check is not set up. Run tiresias guard setup first.");
1028
+ const lib = loadLibraryOrFail();
1029
+ if (lib.meta.model !== cfg.model || lib.meta.prefix !== cfg.prefix)
1030
+ throw new ConfigError("The library was built for another model or prefix than the setting names. Run tiresias guard setup again.");
1031
+ const t = text.trim();
1032
+ if (!t)
1033
+ throw new ConfigError("Usage: tiresias guard check [--file <path> | <text>]");
1034
+ let vectors;
1035
+ try {
1036
+ // v1.2: use local mode's whole-text chunks, limits and vectors, never a prefix prediction.
1037
+ vectors = await textVectors([t], cfg, lib, { private: true }, Date.now() + SETUP_TIMEOUT_MS);
1038
+ }
1039
+ catch (e) {
1040
+ return embedFailed(e, "The endpoint");
1041
+ }
1042
+ const rows = readRows(F.attackRows);
1043
+ let best = -Infinity;
1044
+ let at = 0;
1045
+ const dim = lib.meta.dim;
1046
+ const per = [...lib.groups].map(([collection]) => ({ collection, score: -Infinity, line: lib.meta.lines[collection].threshold, marked: false }));
1047
+ for (const v of vectors.vec.values()) {
1048
+ for (let r = 0; r < lib.meta.attacks.count; r++) {
1049
+ let s = 0;
1050
+ for (let i = 0; i < dim; i++)
1051
+ s += v[i] * lib.attacks[r * dim + i];
1052
+ if (s > best) {
1053
+ best = s;
1054
+ at = r;
1055
+ }
1056
+ }
1057
+ const b = await timedMax(v, lib.ordinary, dim, vectors.time);
1058
+ for (const row of per) {
1059
+ row.score = Math.max(row.score, await timedCollectionScore(v, lib, lib.groups.get(row.collection), b, vectors.time));
1060
+ row.marked = row.score > row.line;
1061
+ }
1062
+ }
1063
+ const isMarked = per.some((x) => x.marked);
1064
+ const near = rows[at] ? { collection: rows[at].c, kind: rows[at].k } : { collection: "unknown", kind: null };
1065
+ const { aimedSignals } = await import("./local.js");
1066
+ const signs = aimedSignals(t);
1067
+ const n = signs + (isMarked ? 1 : 0);
1068
+ return {
1069
+ status: "ok",
1070
+ message: `${isMarked ? "Marked" : "Not marked"}: ${per.map((x) => `${x.collection} ${x.score.toFixed(4)} against its line ${x.line.toFixed(4)}${x.marked ? " (marked)" : ""}`).join(", ")}. Nearest library text: collection "${near.collection}"${near.kind ? `, kind ${near.kind}` : ""}. Pattern signs: ${signs}. In local mode this text would get ${n} sign${n === 1 ? "" : "s"}.`,
1071
+ marked: isMarked,
1072
+ collections: per,
1073
+ nearest: near,
1074
+ pattern_signs: signs,
1075
+ };
1076
+ }
1077
+ // guard off: the setting is removed, and the library with it (its vectors fit one model only, and imported.jsonl
1078
+ // holds the owner's attack texts, which should not outlive the setting that uses them). Rebuild with guard setup.
1079
+ export function off(priv = sessionPrivate()) {
1080
+ if (priv)
1081
+ throw new ConfigError(PRIVATE);
1082
+ return withGuardLock(() => {
1083
+ // The folder is checked first: a link or someone else's folder throws here, before the setting or anything else
1084
+ // is touched.
1085
+ const dir = subDir(GUARD_DIR, false);
1086
+ advanceGuard();
1087
+ const o = readConfigObject();
1088
+ const had = !!o && Object.hasOwn(o, "guard");
1089
+ if (had)
1090
+ confirmedWrite({ name: "guard" }, (x) => void delete x.guard, () => { }, { again: "tiresias guard off" });
1091
+ let removed = false;
1092
+ if (dir && checkSub(dir)) {
1093
+ for (const name of fs.readdirSync(dir)) {
1094
+ const f = path.join(dir, name);
1095
+ if (fs.lstatSync(f).isFile())
1096
+ fs.rmSync(f, { force: true });
1097
+ }
1098
+ fs.rmdirSync(dir);
1099
+ removed = true;
1100
+ }
1101
+ forgetLibrary();
1102
+ const message = had || removed
1103
+ ? `The meaning check is off.${had ? " The setting was removed." : ""}${removed ? " The library (vectors and your imported texts) was deleted; tiresias guard setup builds it again." : ""} Local reads use the pattern check alone.`
1104
+ : "The meaning check was not set up.";
1105
+ return { status: "ok", message, removed_setting: had, removed_library: removed };
1106
+ });
1107
+ }
1108
+ export const MAX_CHECKED = 128; // embedding inputs per reply, including chunks, in the order they are shown
1109
+ // Vectors already computed, by hash of library generation, endpoint, model, prefix and text, in memory only
1110
+ // (never on disk). A cached page read again does not call the endpoint again. Private reads neither use nor fill it.
1111
+ const memo = new LruMap(4_096);
1112
+ const memoKey = (cfg, generation, text) => createHash("sha256").update(JSON.stringify([generation, cfg.url, cfg.model, cfg.prefix, text])).digest("hex");
1113
+ // v1.2: guard check and local reads share complete-text coverage, memoization and input bounds.
1114
+ async function textVectors(texts, cfg, lib, opts, deadline) {
1115
+ // v1.2: cover the whole displayed text, with 256 characters of overlap at chunk boundaries.
1116
+ // Count chunks against the same cap before any request, even when their vectors are memoized.
1117
+ const chunks = new Map();
1118
+ const wanted = new Set();
1119
+ const room = MAX_INPUT_CHARS - cfg.prefix.length;
1120
+ if (room <= 256)
1121
+ throw new ConfigError("The text exceeds the meaning check input limit; it was not checked.");
1122
+ for (const t of new Set(texts)) {
1123
+ const parts = [];
1124
+ for (let start = 0; start < t.length;) {
1125
+ let end = Math.min(start + room, t.length);
1126
+ if (end < t.length && /[\uD800-\uDBFF]/.test(t[end - 1]) && /[\uDC00-\uDFFF]/.test(t[end]))
1127
+ end--;
1128
+ const part = t.slice(start, end);
1129
+ parts.push(part);
1130
+ wanted.add(part);
1131
+ if (wanted.size > MAX_CHECKED)
1132
+ throw new ConfigError("The text exceeds the meaning check input limit; it was not checked.");
1133
+ if (end === t.length)
1134
+ break;
1135
+ start = end - 256;
1136
+ if (/[\uDC00-\uDFFF]/.test(t[start]) && /[\uD800-\uDBFF]/.test(t[start - 1]))
1137
+ start--;
1138
+ }
1139
+ chunks.set(t, parts);
1140
+ }
1141
+ const want = [...wanted];
1142
+ const vec = new Map();
1143
+ const todo = [];
1144
+ for (const t of want) {
1145
+ const hit = opts.private ? undefined : memo.get(memoKey(cfg, lib.meta.generation, t));
1146
+ if (hit && hit.length === lib.meta.dim)
1147
+ vec.set(t, hit);
1148
+ else
1149
+ todo.push(t);
1150
+ }
1151
+ for (let i = 0; i < todo.length; i += MAX_BATCH / 2) {
1152
+ const left = deadline - Date.now();
1153
+ if (left <= 0)
1154
+ throw new ConfigError("The meaning check did not finish; this text was not checked.");
1155
+ const batch = todo.slice(i, i + MAX_BATCH / 2);
1156
+ const vs = await embed(cfg, batch.map((t) => cfg.prefix + t), { timeoutMs: left, signal: opts.signal, dim: lib.meta.dim });
1157
+ batch.forEach((t, k) => {
1158
+ vec.set(t, vs[k]);
1159
+ if (!opts.private)
1160
+ memo.set(memoKey(cfg, lib.meta.generation, t), vs[k]);
1161
+ });
1162
+ }
1163
+ const time = { deadline, yieldAt: Date.now() + 8, signal: opts.signal };
1164
+ return { chunks, vec, time };
1165
+ }
1166
+ export async function meaningCheck(texts, opts = {}) {
1167
+ if (!texts.length)
1168
+ return undefined;
1169
+ let cfg;
1170
+ try {
1171
+ cfg = loadGuard(isOwnerAddress);
1172
+ }
1173
+ catch {
1174
+ // config.json says something about the guard that does not parse: the owner meant it to run.
1175
+ try {
1176
+ const o = readConfigObject();
1177
+ return o && Object.hasOwn(o, "guard") ? { not_run: true } : undefined;
1178
+ }
1179
+ catch {
1180
+ return undefined; // a config.json that does not parse at all: the read itself reports it
1181
+ }
1182
+ }
1183
+ if (!cfg)
1184
+ return undefined;
1185
+ try {
1186
+ const lib = loadLibrary();
1187
+ if (!lib || lib.meta.model !== cfg.model || lib.meta.prefix !== cfg.prefix)
1188
+ return { not_run: true };
1189
+ const deadline = Date.now() + cfg.timeout_seconds * 1000;
1190
+ const { chunks, vec, time } = await textVectors(texts, cfg, lib, opts, deadline);
1191
+ const signs = new Map();
1192
+ const marked = new Set();
1193
+ for (const [t, v] of vec)
1194
+ if (await timedMarked(v, lib, time))
1195
+ marked.add(t);
1196
+ for (const [t, parts] of chunks)
1197
+ if (parts.some(p => marked.has(p)))
1198
+ signs.set(t, 1);
1199
+ checkScoring(time);
1200
+ return { signs };
1201
+ }
1202
+ catch {
1203
+ return { not_run: true };
1204
+ }
1205
+ }
1206
+ export const clearMemo = () => memo.clear();
1207
+ function checkScoring(time) {
1208
+ const now = Date.now();
1209
+ if (time.signal?.aborted || now >= time.deadline)
1210
+ throw new Error("Meaning check did not finish.");
1211
+ return now;
1212
+ }
1213
+ async function timedMax(v, matrix, dim, time, start = 0, count = matrix.length / dim) {
1214
+ let best = -Infinity;
1215
+ const rows = Math.max(1, Math.floor(65_536 / dim));
1216
+ const end = start + count;
1217
+ for (let at = start; at < end; at += rows) {
1218
+ if (checkScoring(time) >= time.yieldAt) {
1219
+ await yieldScoring();
1220
+ time.yieldAt = checkScoring(time) + 8;
1221
+ }
1222
+ best = Math.max(best, maxDot(v, matrix, dim, undefined, at, Math.min(rows, end - at)));
1223
+ }
1224
+ checkScoring(time);
1225
+ return best;
1226
+ }
1227
+ async function timedMarked(v, lib, time) {
1228
+ const b = await timedMax(v, lib.ordinary, lib.meta.dim, time);
1229
+ for (const [c, runs] of lib.groups) {
1230
+ if (await timedCollectionScore(v, lib, runs, b, time) > lib.meta.lines[c].threshold)
1231
+ return true;
1232
+ }
1233
+ return false;
1234
+ }
1235
+ async function timedCollectionScore(v, lib, runs, ordinary, time) {
1236
+ let best = -Infinity;
1237
+ for (const [start, count] of runs)
1238
+ best = Math.max(best, await timedMax(v, lib.attacks, lib.meta.dim, time, start, count));
1239
+ return best - ordinary;
1240
+ }