@deliverd/sdk 0.25.1 → 0.26.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/README.md +65 -0
- package/dist/adapters/index.d.ts +4 -0
- package/dist/adapters/index.d.ts.map +1 -1
- package/dist/adapters/index.js +2 -0
- package/dist/adapters/mastra.d.ts +81 -0
- package/dist/adapters/mastra.d.ts.map +1 -0
- package/dist/adapters/mastra.js +54 -0
- package/dist/adapters/muse-spark.d.ts +79 -0
- package/dist/adapters/muse-spark.d.ts.map +1 -0
- package/dist/adapters/muse-spark.js +59 -0
- package/dist/adapters/shared.d.ts +2 -1
- package/dist/adapters/shared.d.ts.map +1 -1
- package/dist/data-screen.d.ts +233 -0
- package/dist/data-screen.d.ts.map +1 -0
- package/dist/data-screen.js +389 -0
- package/dist/dev.d.ts.map +1 -1
- package/dist/dev.js +42 -2
- package/dist/governance.d.ts +94 -0
- package/dist/governance.d.ts.map +1 -0
- package/dist/governance.js +166 -0
- package/dist/index.d.ts +27 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +30 -0
- package/dist/released.d.ts +1 -1
- package/dist/released.d.ts.map +1 -1
- package/dist/released.js +1265 -0
- package/dist/screen.d.ts +85 -0
- package/dist/screen.d.ts.map +1 -0
- package/dist/screen.js +69 -0
- package/dist/tasks.d.ts +38 -1
- package/dist/tasks.d.ts.map +1 -1
- package/dist/tasks.js +67 -0
- package/dist/types.d.ts +589 -3
- package/dist/types.d.ts.map +1 -1
- package/package.json +2 -2
- package/src/adapters/index.ts +11 -0
- package/src/adapters/mastra.ts +118 -0
- package/src/adapters/muse-spark.ts +147 -0
- package/src/adapters/shared.ts +2 -1
- package/src/data-screen.ts +533 -0
- package/src/dev.ts +45 -2
- package/src/governance.ts +204 -0
- package/src/index.ts +43 -0
- package/src/released.ts +1265 -0
- package/src/screen.ts +144 -0
- package/src/tasks.ts +88 -0
- package/src/types.ts +577 -3
|
@@ -0,0 +1,533 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Screening what an agent is about to send to an AI model.
|
|
3
|
+
*
|
|
4
|
+
* Before a prompt, a document or a retrieved record goes to a model, this
|
|
5
|
+
* finds the personal data, secrets and confidential terms in it, says how
|
|
6
|
+
* sensitive the whole is, and decides — against what the organisation has
|
|
7
|
+
* approved that model to receive — whether it may go as it is, go with the
|
|
8
|
+
* findings replaced by placeholders, go only once a person agrees, or not go.
|
|
9
|
+
*
|
|
10
|
+
* Three lines are held throughout:
|
|
11
|
+
*
|
|
12
|
+
* - **The text need not leave the caller.** Everything here is pure and has no
|
|
13
|
+
* imports, so the SDKs run the same detectors where the agent runs and send
|
|
14
|
+
* Deliverd only counts: "two email addresses, one IBAN". This file is copied
|
|
15
|
+
* verbatim into `packages/sdk/src/data-screen.ts` and into the open-source
|
|
16
|
+
* `packages/screen/src/data-screen.ts`, and a test fails when they differ.
|
|
17
|
+
* - **A finding never carries its value off the machine.** `ScreenFinding` has
|
|
18
|
+
* offsets into the caller's own text; `summarise` keeps only counts.
|
|
19
|
+
* - **Detection is a net, not a guarantee.** Patterns find structured
|
|
20
|
+
* identifiers well and names hardly at all; a name is personal data and
|
|
21
|
+
* nothing here claims to have found every one. Pseudonymised text is still
|
|
22
|
+
* personal data in law. What this buys is fewer identifiers sent, a record of
|
|
23
|
+
* what was, and a person asked when it matters — never a certificate that a
|
|
24
|
+
* prompt is clean.
|
|
25
|
+
*/
|
|
26
|
+
|
|
27
|
+
/** Ordered: the stricter of two classifications is the later one. */
|
|
28
|
+
export const SCREEN_CLASSIFICATIONS = ["public", "internal", "confidential", "restricted"] as const;
|
|
29
|
+
export type ScreenClassification = (typeof SCREEN_CLASSIFICATIONS)[number];
|
|
30
|
+
|
|
31
|
+
export const SCREEN_CATEGORIES = ["personal", "financial", "special", "secret", "confidential"] as const;
|
|
32
|
+
export type ScreenCategory = (typeof SCREEN_CATEGORIES)[number];
|
|
33
|
+
|
|
34
|
+
export const SCREEN_VERDICTS = ["allow", "redact", "ask", "deny"] as const;
|
|
35
|
+
export type ScreenVerdict = (typeof SCREEN_VERDICTS)[number];
|
|
36
|
+
|
|
37
|
+
/** What a policy may do with data the target is not approved for. */
|
|
38
|
+
export type ScreenAction = "redact" | "ask" | "deny";
|
|
39
|
+
|
|
40
|
+
interface KindSpec {
|
|
41
|
+
label: string;
|
|
42
|
+
category: ScreenCategory;
|
|
43
|
+
/** The word in a placeholder: `[EMAIL_1]`. */
|
|
44
|
+
placeholder: string;
|
|
45
|
+
/**
|
|
46
|
+
* Whether replacing the match removes the concern. An IBAN replaced by
|
|
47
|
+
* `[IBAN_1]` is gone; a sentence about someone's diagnosis is still about
|
|
48
|
+
* their diagnosis with the word "diagnosis" taken out.
|
|
49
|
+
*/
|
|
50
|
+
redactable: boolean;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
export const DATA_KINDS = {
|
|
54
|
+
email: { label: "Email address", category: "personal", placeholder: "EMAIL", redactable: true },
|
|
55
|
+
phone: { label: "Phone number", category: "personal", placeholder: "PHONE", redactable: true },
|
|
56
|
+
iban: { label: "IBAN", category: "financial", placeholder: "IBAN", redactable: true },
|
|
57
|
+
payment_card: { label: "Payment card number", category: "financial", placeholder: "CARD", redactable: true },
|
|
58
|
+
uk_national_insurance: { label: "UK National Insurance number", category: "personal", placeholder: "NINO", redactable: true },
|
|
59
|
+
ie_pps: { label: "Irish PPS number", category: "personal", placeholder: "PPS", redactable: true },
|
|
60
|
+
us_ssn: { label: "US Social Security number", category: "personal", placeholder: "SSN", redactable: true },
|
|
61
|
+
ip_address: { label: "IP address", category: "personal", placeholder: "IP", redactable: true },
|
|
62
|
+
date_of_birth: { label: "Date of birth", category: "personal", placeholder: "DOB", redactable: true },
|
|
63
|
+
/** Never found by a pattern here: only by a model detector the caller plugs in (`spans`). */
|
|
64
|
+
person_name: { label: "Person's name", category: "personal", placeholder: "NAME", redactable: true },
|
|
65
|
+
special_category: { label: "Special-category data", category: "special", placeholder: "SPECIAL", redactable: false },
|
|
66
|
+
secret: { label: "Secret or credential", category: "secret", placeholder: "SECRET", redactable: true },
|
|
67
|
+
term: { label: "Confidential term", category: "confidential", placeholder: "TERM", redactable: true },
|
|
68
|
+
} as const satisfies Record<string, KindSpec>;
|
|
69
|
+
|
|
70
|
+
export type DataKind = keyof typeof DATA_KINDS;
|
|
71
|
+
export const DATA_KIND_KEYS = Object.keys(DATA_KINDS) as DataKind[];
|
|
72
|
+
|
|
73
|
+
const CATEGORY_CLASSIFICATION: Record<ScreenCategory, ScreenClassification> = {
|
|
74
|
+
personal: "confidential",
|
|
75
|
+
financial: "confidential",
|
|
76
|
+
confidential: "confidential",
|
|
77
|
+
special: "restricted",
|
|
78
|
+
secret: "restricted",
|
|
79
|
+
};
|
|
80
|
+
|
|
81
|
+
/** Categories that are personal data, for a target approved for none. */
|
|
82
|
+
const PERSONAL_CATEGORIES: ReadonlySet<ScreenCategory> = new Set(["personal", "financial", "special"]);
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* A word or phrase the organisation does not want sent: a client's name, a
|
|
86
|
+
* project's code name, a deal. Matched whole-word and case-insensitively.
|
|
87
|
+
*/
|
|
88
|
+
export interface ScreenTerm {
|
|
89
|
+
term: string;
|
|
90
|
+
/** Shown to people and used in the placeholder: `[CLIENT_1]`. */
|
|
91
|
+
label?: string;
|
|
92
|
+
classification?: "confidential" | "restricted";
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
export interface ScreenFinding {
|
|
96
|
+
kind: DataKind;
|
|
97
|
+
category: ScreenCategory;
|
|
98
|
+
classification: ScreenClassification;
|
|
99
|
+
/** Offsets into the screened text. The value itself is never copied. */
|
|
100
|
+
start: number;
|
|
101
|
+
end: number;
|
|
102
|
+
/** For a term, its label; otherwise the kind's. */
|
|
103
|
+
label: string;
|
|
104
|
+
redactable: boolean;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
export type ScreenCounts = Partial<Record<DataKind, number>>;
|
|
108
|
+
|
|
109
|
+
// ── Detectors ──────────────────────────────────────────────────────────────
|
|
110
|
+
|
|
111
|
+
interface Detector {
|
|
112
|
+
kind: DataKind;
|
|
113
|
+
pattern: RegExp;
|
|
114
|
+
/** A second look at a match a pattern alone cannot judge: a checksum, a digit count. */
|
|
115
|
+
valid?: (match: string) => boolean;
|
|
116
|
+
/** The part of the match that is the value, when the pattern includes context. */
|
|
117
|
+
group?: number;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
const digitsOf = (s: string) => s.replace(/\D/g, "");
|
|
121
|
+
|
|
122
|
+
function luhn(digits: string): boolean {
|
|
123
|
+
let sum = 0;
|
|
124
|
+
let double = false;
|
|
125
|
+
for (let i = digits.length - 1; i >= 0; i--) {
|
|
126
|
+
let d = digits.charCodeAt(i) - 48;
|
|
127
|
+
if (double) {
|
|
128
|
+
d *= 2;
|
|
129
|
+
if (d > 9) d -= 9;
|
|
130
|
+
}
|
|
131
|
+
sum += d;
|
|
132
|
+
double = !double;
|
|
133
|
+
}
|
|
134
|
+
return sum % 10 === 0;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
function ibanValid(raw: string): boolean {
|
|
138
|
+
const iban = raw.replace(/\s/g, "").toUpperCase();
|
|
139
|
+
if (iban.length < 15 || iban.length > 34) return false;
|
|
140
|
+
const moved = iban.slice(4) + iban.slice(0, 4);
|
|
141
|
+
let remainder = 0;
|
|
142
|
+
for (const ch of moved) {
|
|
143
|
+
const code = ch.charCodeAt(0);
|
|
144
|
+
const value = code >= 65 && code <= 90 ? String(code - 55) : ch;
|
|
145
|
+
for (const digit of value) remainder = (remainder * 10 + (digit.charCodeAt(0) - 48)) % 97;
|
|
146
|
+
}
|
|
147
|
+
return remainder === 1;
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/** The PPS check character: weights 8 to 2 on the digits, 9 on a second letter, mod 23, 0 is W. */
|
|
151
|
+
function ppsValid(raw: string): boolean {
|
|
152
|
+
const m = /^(\d{7})([A-W])([A-IW]?)$/.exec(raw.toUpperCase());
|
|
153
|
+
if (!m) return false;
|
|
154
|
+
let sum = 0;
|
|
155
|
+
for (let i = 0; i < 7; i++) sum += (m[1]!.charCodeAt(i) - 48) * (8 - i);
|
|
156
|
+
if (m[3]) sum += (m[3] === "W" ? 0 : m[3].charCodeAt(0) - 64) * 9;
|
|
157
|
+
const r = sum % 23;
|
|
158
|
+
return m[2] === (r === 0 ? "W" : String.fromCharCode(64 + r));
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
function ipv4Valid(raw: string): boolean {
|
|
162
|
+
const parts = raw.split(".").map(Number);
|
|
163
|
+
if (parts.length !== 4 || parts.some((p) => p > 255)) return false;
|
|
164
|
+
// Loopback and the unspecified address identify nobody.
|
|
165
|
+
return parts[0] !== 127 && parts[0] !== 0;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* Credential patterns. The same set the publish scanner blocks a report for,
|
|
170
|
+
* because a key that must not be published must not be sent to a model either.
|
|
171
|
+
*/
|
|
172
|
+
const SECRET_PATTERNS: RegExp[] = [
|
|
173
|
+
/\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g,
|
|
174
|
+
/-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP )?PRIVATE KEY(?: BLOCK)?-----/g,
|
|
175
|
+
/\bgh[pousr]_[A-Za-z0-9]{36,255}\b/g,
|
|
176
|
+
/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g,
|
|
177
|
+
/\b[sr]k_(?:live|test)_[A-Za-z0-9]{20,}\b/g,
|
|
178
|
+
/\bsk-ant-[A-Za-z0-9_-]{24,}\b/g,
|
|
179
|
+
/\bsk-(?:proj-)?[A-Za-z0-9_-]{32,}\b/g,
|
|
180
|
+
/\bAIza[0-9A-Za-z_-]{35}\b/g,
|
|
181
|
+
/\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g,
|
|
182
|
+
/\b(?:password|passwd|secret_key|api_key|apikey|auth_token)\s*[:=]\s*["'][^"']{8,}["']/gi,
|
|
183
|
+
/\b(?:dlv|dlvk)_[A-Za-z0-9]{24,}\b/g,
|
|
184
|
+
];
|
|
185
|
+
|
|
186
|
+
/**
|
|
187
|
+
* Words that say a passage is about special-category data (GDPR Article 9,
|
|
188
|
+
* and criminal-offence data under Article 10). A keyword is a weak signal, so
|
|
189
|
+
* it is never redacted away: it sends the passage to a person when the target
|
|
190
|
+
* is not approved for restricted personal data.
|
|
191
|
+
*/
|
|
192
|
+
const SPECIAL_PATTERN =
|
|
193
|
+
/\b(?:diagnos(?:is|ed|es)|medical (?:record|history|condition)s?|mental health|prescri(?:bed|ption)s?|HIV|pregnan(?:t|cy)|disabilit(?:y|ies)|sexual orientation|religious belief|ethnic origin|racial origin|trade union member(?:ship)?|biometric|genetic data|criminal (?:record|conviction|offence)s?)\b/gi;
|
|
194
|
+
|
|
195
|
+
const DETECTORS: Detector[] = [
|
|
196
|
+
...SECRET_PATTERNS.map((pattern) => ({ kind: "secret" as const, pattern })),
|
|
197
|
+
{ kind: "iban", pattern: /\b[A-Z]{2}\d{2}(?: ?[A-Z0-9]{4}){2,7}(?: ?[A-Z0-9]{1,4})?\b/g, valid: ibanValid },
|
|
198
|
+
{
|
|
199
|
+
kind: "payment_card",
|
|
200
|
+
pattern: /\b[2-6]\d{3}(?:[ -]?\d{4}){2}[ -]?\d{1,7}\b/g,
|
|
201
|
+
valid: (m) => {
|
|
202
|
+
const d = digitsOf(m);
|
|
203
|
+
return d.length >= 13 && d.length <= 19 && luhn(d);
|
|
204
|
+
},
|
|
205
|
+
},
|
|
206
|
+
{ kind: "us_ssn", pattern: /\b(?!000|666|9\d\d)\d{3}-(?!00)\d{2}-(?!0000)\d{4}\b/g },
|
|
207
|
+
{
|
|
208
|
+
kind: "uk_national_insurance",
|
|
209
|
+
pattern: /\b(?!BG|GB|NK|KN|TN|NT|ZZ)[A-CEGHJ-PR-TW-Z][A-CEGHJ-NPR-TW-Z] ?\d{2} ?\d{2} ?\d{2} ?[A-D]\b/g,
|
|
210
|
+
},
|
|
211
|
+
{ kind: "ie_pps", pattern: /\b\d{7}[A-W][A-IW]?\b/g, valid: ppsValid },
|
|
212
|
+
{ kind: "email", pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}\b/g },
|
|
213
|
+
{
|
|
214
|
+
kind: "date_of_birth",
|
|
215
|
+
pattern: /\b(?:date of birth|d\.?o\.?b\.?|born(?: on)?)\s*[:\-]?\s*(\d{1,2}[\/.\-]\d{1,2}[\/.\-]\d{2,4}|\d{4}-\d{2}-\d{2}|\d{1,2} (?:jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)[a-z]* \d{4})/gi,
|
|
216
|
+
group: 1,
|
|
217
|
+
},
|
|
218
|
+
{
|
|
219
|
+
kind: "phone",
|
|
220
|
+
// An international number, or a national one starting with 0: a bare run
|
|
221
|
+
// of digits is far more often an amount, an id or a date.
|
|
222
|
+
pattern: /(?<![\w+])(?:\+\d{1,3}[ .-]?(?:\(0\)[ .-]?)?|\(?0)\d{1,4}\)?(?:[ .-]?\d{2,4}){2,4}(?![\w])/g,
|
|
223
|
+
valid: (m) => {
|
|
224
|
+
const d = digitsOf(m);
|
|
225
|
+
return d.length >= 9 && d.length <= 15;
|
|
226
|
+
},
|
|
227
|
+
},
|
|
228
|
+
{ kind: "ip_address", pattern: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g, valid: ipv4Valid },
|
|
229
|
+
{ kind: "special_category", pattern: SPECIAL_PATTERN },
|
|
230
|
+
];
|
|
231
|
+
|
|
232
|
+
/** Earlier wins an overlap: a card number is not also a phone number. */
|
|
233
|
+
const PRIORITY: Record<DataKind, number> = Object.fromEntries(
|
|
234
|
+
["secret", "iban", "payment_card", "us_ssn", "uk_national_insurance", "ie_pps", "email", "date_of_birth", "phone", "ip_address", "term", "person_name", "special_category"].map(
|
|
235
|
+
(k, i) => [k, i]
|
|
236
|
+
)
|
|
237
|
+
) as Record<DataKind, number>;
|
|
238
|
+
|
|
239
|
+
const escapeRegExp = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
240
|
+
|
|
241
|
+
/** Terms past this are ignored, so a pasted list cannot make every screen slow. */
|
|
242
|
+
export const MAX_SCREEN_TERMS = 500;
|
|
243
|
+
|
|
244
|
+
/**
|
|
245
|
+
* What another detector found — a named-entity model, a DLP service — handed
|
|
246
|
+
* in as offsets into the same text. Patterns cannot find names; a model can,
|
|
247
|
+
* and this is where its answer joins theirs.
|
|
248
|
+
*/
|
|
249
|
+
export interface DetectedSpan {
|
|
250
|
+
kind: DataKind;
|
|
251
|
+
start: number;
|
|
252
|
+
end: number;
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
/**
|
|
256
|
+
* A detector to run beside the patterns: a function from the text to its
|
|
257
|
+
* spans. The open-source `@deliverd/screen` package has adapters that turn a
|
|
258
|
+
* Hugging Face token classifier or a Presidio analyzer into one.
|
|
259
|
+
*/
|
|
260
|
+
export type SpanDetector = (text: string) => readonly DetectedSpan[] | Promise<readonly DetectedSpan[]>;
|
|
261
|
+
|
|
262
|
+
/**
|
|
263
|
+
* Find what is in a text. Overlapping matches keep the stronger kind, so each
|
|
264
|
+
* character belongs to at most one finding. `spans` are another detector's
|
|
265
|
+
* findings, held to the same rules; one outside the text or of no known kind
|
|
266
|
+
* is dropped.
|
|
267
|
+
*/
|
|
268
|
+
export function screenText(text: string, terms: readonly ScreenTerm[] = [], spans: readonly DetectedSpan[] = []): ScreenFinding[] {
|
|
269
|
+
const raw: ScreenFinding[] = [];
|
|
270
|
+
const add = (kind: DataKind, start: number, end: number, label?: string, classification?: ScreenClassification) => {
|
|
271
|
+
const spec = DATA_KINDS[kind];
|
|
272
|
+
raw.push({
|
|
273
|
+
kind,
|
|
274
|
+
category: spec.category,
|
|
275
|
+
classification: classification ?? CATEGORY_CLASSIFICATION[spec.category],
|
|
276
|
+
start,
|
|
277
|
+
end,
|
|
278
|
+
label: label ?? spec.label,
|
|
279
|
+
redactable: spec.redactable,
|
|
280
|
+
});
|
|
281
|
+
};
|
|
282
|
+
|
|
283
|
+
for (const d of DETECTORS) {
|
|
284
|
+
d.pattern.lastIndex = 0;
|
|
285
|
+
for (const m of text.matchAll(d.pattern)) {
|
|
286
|
+
const value = d.group ? m[d.group] : m[0];
|
|
287
|
+
if (!value || (d.valid && !d.valid(value))) continue;
|
|
288
|
+
const start = d.group ? m.index! + m[0].lastIndexOf(value) : m.index!;
|
|
289
|
+
add(d.kind, start, start + value.length);
|
|
290
|
+
}
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
for (const t of terms.slice(0, MAX_SCREEN_TERMS)) {
|
|
294
|
+
const term = t.term.trim();
|
|
295
|
+
if (term.length < 2) continue;
|
|
296
|
+
const pattern = new RegExp(`(?<![\\p{L}\\p{N}])${escapeRegExp(term)}(?![\\p{L}\\p{N}])`, "giu");
|
|
297
|
+
for (const m of text.matchAll(pattern)) {
|
|
298
|
+
add("term", m.index!, m.index! + m[0].length, t.label?.trim() || DATA_KINDS.term.label, t.classification ?? "confidential");
|
|
299
|
+
}
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
for (const s of spans) {
|
|
303
|
+
if (!Object.hasOwn(DATA_KINDS, s.kind) || s.kind === "term") continue;
|
|
304
|
+
if (!Number.isInteger(s.start) || !Number.isInteger(s.end) || s.start < 0 || s.end > text.length || s.end <= s.start) continue;
|
|
305
|
+
add(s.kind, s.start, s.end);
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
raw.sort((a, b) => PRIORITY[a.kind] - PRIORITY[b.kind] || b.end - b.start - (a.end - a.start) || a.start - b.start);
|
|
309
|
+
const kept: ScreenFinding[] = [];
|
|
310
|
+
for (const f of raw) {
|
|
311
|
+
if (kept.some((k) => f.start < k.end && k.start < f.end)) continue;
|
|
312
|
+
kept.push(f);
|
|
313
|
+
}
|
|
314
|
+
return kept.sort((a, b) => a.start - b.start);
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
/** Counts only: what goes over the wire when the text stays where it is. */
|
|
318
|
+
export function summarise(findings: readonly ScreenFinding[]): ScreenCounts {
|
|
319
|
+
const counts: ScreenCounts = {};
|
|
320
|
+
for (const f of findings) counts[f.kind] = (counts[f.kind] ?? 0) + 1;
|
|
321
|
+
return counts;
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
// ── Redaction ──────────────────────────────────────────────────────────────
|
|
325
|
+
|
|
326
|
+
export interface Redaction {
|
|
327
|
+
text: string;
|
|
328
|
+
/** Placeholder to original value. Stays with the caller; never sent anywhere. */
|
|
329
|
+
replacements: Record<string, string>;
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
const placeholderWord = (f: ScreenFinding) =>
|
|
333
|
+
f.kind === "term" && f.label !== DATA_KINDS.term.label
|
|
334
|
+
? f.label.toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_|_$/g, "").slice(0, 24) || "TERM"
|
|
335
|
+
: DATA_KINDS[f.kind].placeholder;
|
|
336
|
+
|
|
337
|
+
/**
|
|
338
|
+
* Replace each redactable finding with a placeholder. The same value gets the
|
|
339
|
+
* same placeholder throughout, so a model can still tell that two mentions are
|
|
340
|
+
* one person, and `restore` can put the values back in its answer.
|
|
341
|
+
*/
|
|
342
|
+
export function redact(text: string, findings: readonly ScreenFinding[]): Redaction {
|
|
343
|
+
const replacements: Record<string, string> = {};
|
|
344
|
+
const byValue = new Map<string, string>();
|
|
345
|
+
const counters = new Map<string, number>();
|
|
346
|
+
let out = "";
|
|
347
|
+
let at = 0;
|
|
348
|
+
for (const f of [...findings].sort((a, b) => a.start - b.start)) {
|
|
349
|
+
if (!f.redactable || f.start < at) continue;
|
|
350
|
+
const value = text.slice(f.start, f.end);
|
|
351
|
+
const key = `${f.kind}\u0000${value.toLowerCase()}`;
|
|
352
|
+
let placeholder = byValue.get(key);
|
|
353
|
+
if (!placeholder) {
|
|
354
|
+
const word = placeholderWord(f);
|
|
355
|
+
const n = (counters.get(word) ?? 0) + 1;
|
|
356
|
+
counters.set(word, n);
|
|
357
|
+
placeholder = `[${word}_${n}]`;
|
|
358
|
+
byValue.set(key, placeholder);
|
|
359
|
+
replacements[placeholder] = value;
|
|
360
|
+
}
|
|
361
|
+
out += text.slice(at, f.start) + placeholder;
|
|
362
|
+
at = f.end;
|
|
363
|
+
}
|
|
364
|
+
return { text: out + text.slice(at), replacements };
|
|
365
|
+
}
|
|
366
|
+
|
|
367
|
+
/** Put the original values back into text a model wrote using the placeholders. */
|
|
368
|
+
export function restore(text: string, replacements: Readonly<Record<string, string>>): string {
|
|
369
|
+
const keys = Object.keys(replacements).sort((a, b) => b.length - a.length);
|
|
370
|
+
if (keys.length === 0) return text;
|
|
371
|
+
const pattern = new RegExp(keys.map(escapeRegExp).join("|"), "g");
|
|
372
|
+
return text.replace(pattern, (p) => replacements[p] ?? p);
|
|
373
|
+
}
|
|
374
|
+
|
|
375
|
+
// ── Deciding ───────────────────────────────────────────────────────────────
|
|
376
|
+
|
|
377
|
+
/** What the destination model is approved to receive: the AI register's record. */
|
|
378
|
+
export interface ScreenTarget {
|
|
379
|
+
name: string;
|
|
380
|
+
/** The highest classification approved; null when the record does not say. */
|
|
381
|
+
approvedClassification: ScreenClassification | null;
|
|
382
|
+
personalData: boolean;
|
|
383
|
+
active: boolean;
|
|
384
|
+
}
|
|
385
|
+
|
|
386
|
+
export interface ScreenPolicy {
|
|
387
|
+
/** Secrets and credentials. Default deny: a key sent to a model is a key disclosed. */
|
|
388
|
+
secrets: ScreenAction;
|
|
389
|
+
/** Redactable data the target is not approved for. Default redact. */
|
|
390
|
+
beyondApproval: ScreenAction;
|
|
391
|
+
/** Data that redaction cannot fix (special category) the target is not approved for. Default ask. */
|
|
392
|
+
notRedactable: "ask" | "deny";
|
|
393
|
+
/** What an unnamed target is taken to be approved for. Default internal, no personal data. */
|
|
394
|
+
unregistered: { approvedClassification: ScreenClassification; personalData: boolean };
|
|
395
|
+
}
|
|
396
|
+
|
|
397
|
+
export const DEFAULT_SCREEN_POLICY: ScreenPolicy = {
|
|
398
|
+
secrets: "deny",
|
|
399
|
+
beyondApproval: "redact",
|
|
400
|
+
notRedactable: "ask",
|
|
401
|
+
unregistered: { approvedClassification: "internal", personalData: false },
|
|
402
|
+
};
|
|
403
|
+
|
|
404
|
+
export interface ScreenAssessment {
|
|
405
|
+
verdict: ScreenVerdict;
|
|
406
|
+
/** The classification of what was found; public when nothing was. */
|
|
407
|
+
classification: ScreenClassification;
|
|
408
|
+
personalData: boolean;
|
|
409
|
+
categories: ScreenCategory[];
|
|
410
|
+
/** The kinds behind the verdict: what redaction replaces, and what a person is asked about. */
|
|
411
|
+
offending: DataKind[];
|
|
412
|
+
/** One sentence each, for the agent and for the person asked. */
|
|
413
|
+
reasons: string[];
|
|
414
|
+
}
|
|
415
|
+
|
|
416
|
+
const rank = (c: ScreenClassification) => SCREEN_CLASSIFICATIONS.indexOf(c);
|
|
417
|
+
const VERDICT_RANK: Record<ScreenVerdict, number> = { allow: 0, redact: 1, ask: 2, deny: 3 };
|
|
418
|
+
const stricter = (a: ScreenVerdict, b: ScreenVerdict) => (VERDICT_RANK[b] > VERDICT_RANK[a] ? b : a);
|
|
419
|
+
|
|
420
|
+
/** Reads a stored or sent policy, keeping a default for anything missing or unknown. */
|
|
421
|
+
export function readScreenPolicy(raw: unknown): ScreenPolicy {
|
|
422
|
+
const p = (raw && typeof raw === "object" ? raw : {}) as Record<string, unknown>;
|
|
423
|
+
const actions = ["redact", "ask", "deny"];
|
|
424
|
+
const pick = <T extends string>(v: unknown, allowed: readonly string[], fallback: T): T =>
|
|
425
|
+
typeof v === "string" && allowed.includes(v) ? (v as T) : fallback;
|
|
426
|
+
const u = (p.unregistered && typeof p.unregistered === "object" ? p.unregistered : {}) as Record<string, unknown>;
|
|
427
|
+
return {
|
|
428
|
+
secrets: pick(p.secrets, actions, DEFAULT_SCREEN_POLICY.secrets),
|
|
429
|
+
beyondApproval: pick(p.beyondApproval, actions, DEFAULT_SCREEN_POLICY.beyondApproval),
|
|
430
|
+
notRedactable: pick(p.notRedactable, ["ask", "deny"], DEFAULT_SCREEN_POLICY.notRedactable),
|
|
431
|
+
unregistered: {
|
|
432
|
+
approvedClassification: pick(u.approvedClassification, SCREEN_CLASSIFICATIONS, DEFAULT_SCREEN_POLICY.unregistered.approvedClassification),
|
|
433
|
+
personalData: typeof u.personalData === "boolean" ? u.personalData : DEFAULT_SCREEN_POLICY.unregistered.personalData,
|
|
434
|
+
},
|
|
435
|
+
};
|
|
436
|
+
}
|
|
437
|
+
|
|
438
|
+
const plural = (n: number, label: string) => `${n} ${label.toLowerCase()}${n === 1 ? "" : "s"}`;
|
|
439
|
+
|
|
440
|
+
/** "2 email addresses and 1 IBAN", for a reason or an approval's title. */
|
|
441
|
+
export function describeCounts(counts: ScreenCounts): string {
|
|
442
|
+
const parts = DATA_KIND_KEYS.filter((k) => (counts[k] ?? 0) > 0).map((k) => {
|
|
443
|
+
const n = counts[k]!;
|
|
444
|
+
const label = DATA_KINDS[k].label;
|
|
445
|
+
if (k === "email") return `${n} email address${n === 1 ? "" : "es"}`;
|
|
446
|
+
if (k === "special_category") return `${n} mention${n === 1 ? "" : "s"} of special-category data`;
|
|
447
|
+
if (k === "secret") return `${n} secret${n === 1 ? "" : "s"} or credential${n === 1 ? "" : "s"}`;
|
|
448
|
+
if (k === "term") return plural(n, "confidential term");
|
|
449
|
+
if (k === "person_name") return `${n} ${n === 1 ? "person's name" : "people's names"}`;
|
|
450
|
+
return /^[A-Z]{2,}/.test(label) ? `${n} ${label}${n === 1 ? "" : "s"}` : plural(n, label);
|
|
451
|
+
});
|
|
452
|
+
if (parts.length <= 1) return parts[0] ?? "nothing";
|
|
453
|
+
return `${parts.slice(0, -1).join(", ")} and ${parts.at(-1)}`;
|
|
454
|
+
}
|
|
455
|
+
|
|
456
|
+
/**
|
|
457
|
+
* Decide from counts alone, so the same answer comes back whether the text was
|
|
458
|
+
* screened here or on the caller's machine.
|
|
459
|
+
*
|
|
460
|
+
* `termClassification` is the strictest classification among the terms found,
|
|
461
|
+
* which counts cannot carry; restricted when a caller says so.
|
|
462
|
+
*/
|
|
463
|
+
export function assessCounts(
|
|
464
|
+
counts: ScreenCounts,
|
|
465
|
+
target: ScreenTarget | null,
|
|
466
|
+
policy: ScreenPolicy = DEFAULT_SCREEN_POLICY,
|
|
467
|
+
termClassification: ScreenClassification = "confidential"
|
|
468
|
+
): ScreenAssessment {
|
|
469
|
+
const present = DATA_KIND_KEYS.filter((k) => (counts[k] ?? 0) > 0);
|
|
470
|
+
const categories = SCREEN_CATEGORIES.filter((c) => present.some((k) => DATA_KINDS[k].category === c));
|
|
471
|
+
const classOf = (k: DataKind) => (k === "term" ? termClassification : CATEGORY_CLASSIFICATION[DATA_KINDS[k].category]);
|
|
472
|
+
const classification = present.reduce<ScreenClassification>((acc, k) => (rank(classOf(k)) > rank(acc) ? classOf(k) : acc), "public");
|
|
473
|
+
const personalData = categories.some((c) => PERSONAL_CATEGORIES.has(c));
|
|
474
|
+
|
|
475
|
+
const reasons: string[] = [];
|
|
476
|
+
const offending: DataKind[] = [];
|
|
477
|
+
let verdict: ScreenVerdict = "allow";
|
|
478
|
+
|
|
479
|
+
if (target && !target.active) {
|
|
480
|
+
return {
|
|
481
|
+
verdict: "deny",
|
|
482
|
+
classification,
|
|
483
|
+
personalData,
|
|
484
|
+
categories,
|
|
485
|
+
offending: present,
|
|
486
|
+
reasons: [`${target.name} is not an active system in the AI register, so nothing should be sent to it.`],
|
|
487
|
+
};
|
|
488
|
+
}
|
|
489
|
+
if (present.length === 0) return { verdict, classification, personalData, categories, offending, reasons };
|
|
490
|
+
|
|
491
|
+
const name = target?.name ?? "an AI system that is not in the register";
|
|
492
|
+
const approved = target ? target.approvedClassification ?? policy.unregistered.approvedClassification : policy.unregistered.approvedClassification;
|
|
493
|
+
const personalApproved = target ? target.personalData : policy.unregistered.personalData;
|
|
494
|
+
|
|
495
|
+
const secrets = counts.secret ?? 0;
|
|
496
|
+
if (secrets > 0) {
|
|
497
|
+
verdict = stricter(verdict, policy.secrets);
|
|
498
|
+
offending.push("secret");
|
|
499
|
+
reasons.push(`It contains ${describeCounts({ secret: secrets })}, which should never be sent to a model.`);
|
|
500
|
+
}
|
|
501
|
+
|
|
502
|
+
for (const k of present) {
|
|
503
|
+
if (k === "secret") continue;
|
|
504
|
+
const tooSensitive = rank(classOf(k)) > rank(approved);
|
|
505
|
+
const personalNotApproved = DATA_KINDS[k].category !== "confidential" && !personalApproved;
|
|
506
|
+
if (!tooSensitive && !personalNotApproved) continue;
|
|
507
|
+
const action: ScreenAction = DATA_KINDS[k].redactable ? policy.beyondApproval : policy.notRedactable;
|
|
508
|
+
verdict = stricter(verdict, action);
|
|
509
|
+
offending.push(k);
|
|
510
|
+
const why = personalNotApproved
|
|
511
|
+
? "which is not approved to receive personal data"
|
|
512
|
+
: `which is approved for ${approved} data at most`;
|
|
513
|
+
reasons.push(`It contains ${describeCounts({ [k]: counts[k] })}, and goes to ${name}, ${why}.`);
|
|
514
|
+
}
|
|
515
|
+
|
|
516
|
+
return { verdict, classification, personalData, categories, offending, reasons };
|
|
517
|
+
}
|
|
518
|
+
|
|
519
|
+
/**
|
|
520
|
+
* The text with the findings behind a verdict replaced: only those, so data
|
|
521
|
+
* the target is approved for still reaches it. What a person asked is shown,
|
|
522
|
+
* and what a `redact` verdict sends. Null for a deny, which sends nothing.
|
|
523
|
+
*/
|
|
524
|
+
export function redactFor(text: string, findings: readonly ScreenFinding[], assessment: Pick<ScreenAssessment, "verdict" | "offending">): Redaction | null {
|
|
525
|
+
if (assessment.verdict === "deny") return null;
|
|
526
|
+
const offending = new Set(assessment.offending);
|
|
527
|
+
return redact(text, findings.filter((f) => offending.has(f.kind)));
|
|
528
|
+
}
|
|
529
|
+
|
|
530
|
+
/** The strictest classification among the terms found, for `assessCounts`. */
|
|
531
|
+
export function termClassificationOf(findings: readonly ScreenFinding[]): ScreenClassification {
|
|
532
|
+
return findings.some((f) => f.kind === "term" && f.classification === "restricted") ? "restricted" : "confidential";
|
|
533
|
+
}
|
package/src/dev.ts
CHANGED
|
@@ -11,6 +11,7 @@ import type {
|
|
|
11
11
|
TaskNode,
|
|
12
12
|
TaskState,
|
|
13
13
|
} from "./types.js";
|
|
14
|
+
import { assessCounts, DEFAULT_SCREEN_POLICY, describeCounts, type ScreenCounts } from "./data-screen.js";
|
|
14
15
|
|
|
15
16
|
/**
|
|
16
17
|
* Development mode: the whole loop, on your machine, with nobody in it.
|
|
@@ -95,7 +96,7 @@ export function developmentFetch(options: DevelopmentOptions = {}): typeof globa
|
|
|
95
96
|
const flowStore = new Map<string, FlowData>();
|
|
96
97
|
const tasks = developmentTasks(options);
|
|
97
98
|
|
|
98
|
-
|
|
99
|
+
const handle = (async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
|
|
99
100
|
const url = new URL(String(input));
|
|
100
101
|
const path = url.pathname.replace(/^\/api\/v1/, "");
|
|
101
102
|
const method = (init?.method ?? "GET").toUpperCase();
|
|
@@ -658,6 +659,47 @@ export function developmentFetch(options: DevelopmentOptions = {}): typeof globa
|
|
|
658
659
|
return json({ tasks: tasks.list(url.searchParams), nextCursor: null });
|
|
659
660
|
}
|
|
660
661
|
|
|
662
|
+
/*
|
|
663
|
+
* Screening with no organisation behind it: no register record and no
|
|
664
|
+
* policy, so the defaults decide — internal data and no personal data
|
|
665
|
+
* approved — and an `ask` files an ordinary development approval, which
|
|
666
|
+
* the imaginary approver decides like any other.
|
|
667
|
+
*/
|
|
668
|
+
if (method === "POST" && path === "/screen") {
|
|
669
|
+
const counts = (body.counts ?? {}) as ScreenCounts;
|
|
670
|
+
const termClassification = body.termClassification === "restricted" ? "restricted" : "confidential";
|
|
671
|
+
const assessment = assessCounts(counts, null, DEFAULT_SCREEN_POLICY, termClassification);
|
|
672
|
+
let approval: { id: string; url: string; status: string } | null = null;
|
|
673
|
+
if (assessment.verdict === "ask" && body.ask !== false) {
|
|
674
|
+
const created = (await (
|
|
675
|
+
await handle(`${url.origin}/api/v1/approvals`, {
|
|
676
|
+
method: "POST",
|
|
677
|
+
body: JSON.stringify({
|
|
678
|
+
title: `Send ${describeCounts(counts)} to an AI model?`,
|
|
679
|
+
description: assessment.reasons.join("\n"),
|
|
680
|
+
risk: assessment.classification === "restricted" ? "high" : "medium",
|
|
681
|
+
externalId: body.externalId,
|
|
682
|
+
}),
|
|
683
|
+
})
|
|
684
|
+
).json()) as ApprovalData;
|
|
685
|
+
approval = { id: created.id, url: created.url, status: created.status };
|
|
686
|
+
}
|
|
687
|
+
return json({
|
|
688
|
+
verdict: assessment.verdict,
|
|
689
|
+
allowed: assessment.verdict === "allow" || assessment.verdict === "redact",
|
|
690
|
+
classification: assessment.classification,
|
|
691
|
+
personalData: assessment.personalData,
|
|
692
|
+
categories: assessment.categories,
|
|
693
|
+
counts,
|
|
694
|
+
offending: assessment.offending,
|
|
695
|
+
reasons: assessment.reasons,
|
|
696
|
+
target: null,
|
|
697
|
+
findings: null,
|
|
698
|
+
redactedText: null,
|
|
699
|
+
approval,
|
|
700
|
+
});
|
|
701
|
+
}
|
|
702
|
+
|
|
661
703
|
const taskMatch = /^\/tasks\/([^/]+)(?:\/(context|graph|side-tasks|findings|complete|apply|reopen|cancel|links))?$/.exec(path);
|
|
662
704
|
if (taskMatch) {
|
|
663
705
|
const [status, payload] = tasks.act(method, taskMatch[1]!, taskMatch[2] ?? null, body);
|
|
@@ -668,12 +710,13 @@ export function developmentFetch(options: DevelopmentOptions = {}): typeof globa
|
|
|
668
710
|
{
|
|
669
711
|
error: {
|
|
670
712
|
code: "not_in_development_mode",
|
|
671
|
-
message: `Development mode simulates approvals, reviews, collections, flows and
|
|
713
|
+
message: `Development mode simulates approvals, reviews, collections, flows, tasks and screening only, and something called ${method} ${path}. Use a real API key for the rest of the API.`,
|
|
672
714
|
},
|
|
673
715
|
},
|
|
674
716
|
501
|
|
675
717
|
);
|
|
676
718
|
}) as typeof globalThis.fetch;
|
|
719
|
+
return handle;
|
|
677
720
|
}
|
|
678
721
|
|
|
679
722
|
function resolveOutcome(
|