@crewhaus/tool-kyc 0.7.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 +216 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.js +821 -0
- package/dist/lib/entity.d.ts +94 -0
- package/dist/lib/entity.js +230 -0
- package/dist/lib/names.d.ts +136 -0
- package/dist/lib/names.js +330 -0
- package/dist/lib/net.d.ts +151 -0
- package/dist/lib/net.js +399 -0
- package/dist/lib/screen.d.ts +186 -0
- package/dist/lib/screen.js +409 -0
- package/dist/lib/vat.d.ts +137 -0
- package/dist/lib/vat.js +388 -0
- package/dist/paths.d.ts +42 -0
- package/dist/paths.js +158 -0
- package/package.json +47 -0
package/dist/lib/net.js
ADDED
|
@@ -0,0 +1,399 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The network posture for `@crewhaus/tool-kyc`.
|
|
3
|
+
*
|
|
4
|
+
* Two of this package's three tools read a public register over HTTPS, and
|
|
5
|
+
* every byte they send leaves through `getJson`. As in `@crewhaus/tool-registry`,
|
|
6
|
+
* no caller supplies a URL, a host or an origin: a caller supplies a VAT id,
|
|
7
|
+
* an LEI, a CIK or a ticker, the value is checked against its own grammar, and
|
|
8
|
+
* the URL is built from one of the constants below. There is no allow-list to
|
|
9
|
+
* widen.
|
|
10
|
+
*
|
|
11
|
+
* No request carries a credential. VIES, HMRC's VAT checker, GLEIF and SEC
|
|
12
|
+
* EDGAR are all open-access endpoints; there is nothing to put in an
|
|
13
|
+
* `Authorization` header, so there is nothing to leak at a redirect. If one of
|
|
14
|
+
* them ever answers 401 or 403, that is reported as *could-not-check* with the
|
|
15
|
+
* status in it, never as "not registered" — see `ALWAYS THREE OUTCOMES` in the
|
|
16
|
+
* README.
|
|
17
|
+
*
|
|
18
|
+
* The SSRF gate and the connect-time IP pin live in the default dialler, which
|
|
19
|
+
* is what `_setKycFetch` replaces, so no test in this package resolves a name
|
|
20
|
+
* or opens a socket.
|
|
21
|
+
*/
|
|
22
|
+
import { CrewhausError } from "@crewhaus/errors";
|
|
23
|
+
import { assertNotSsrf } from "@crewhaus/tool-fetch";
|
|
24
|
+
/** A refusal by the origin rule, the redirect rule or the byte cap. */
|
|
25
|
+
export class KycNetworkError extends CrewhausError {
|
|
26
|
+
name = "KycNetworkError";
|
|
27
|
+
constructor(message) {
|
|
28
|
+
super("tool", message);
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Every origin this package can dial, and the only ones.
|
|
33
|
+
*
|
|
34
|
+
* `www.sec.gov` is here as well as `data.sec.gov` because EDGAR's
|
|
35
|
+
* ticker→CIK map is published on the website host while the submissions
|
|
36
|
+
* documents are on the data host — one company lookup by ticker legitimately
|
|
37
|
+
* touches both.
|
|
38
|
+
*/
|
|
39
|
+
export const ORIGINS = Object.freeze({
|
|
40
|
+
/** VIES, the EU's proxy to the member states' own VAT systems. */
|
|
41
|
+
vies: "https://ec.europa.eu",
|
|
42
|
+
/** HMRC's VAT check-a-number API. VIES has not covered GB since 2021. */
|
|
43
|
+
hmrc: "https://api.service.hmrc.gov.uk",
|
|
44
|
+
/** GLEIF, the LEI issuer of record. */
|
|
45
|
+
gleif: "https://api.gleif.org",
|
|
46
|
+
/** EDGAR submissions. */
|
|
47
|
+
edgarData: "https://data.sec.gov",
|
|
48
|
+
/** EDGAR's ticker→CIK map. */
|
|
49
|
+
edgarFiles: "https://www.sec.gov",
|
|
50
|
+
});
|
|
51
|
+
const ALLOWED_ORIGINS = new Set(Object.values(ORIGINS));
|
|
52
|
+
/**
|
|
53
|
+
* SEC asks every automated reader for a User-Agent that identifies the caller
|
|
54
|
+
* and says where to complain, and answers 403 without one. The others do not
|
|
55
|
+
* care, so one header for all four keeps the request path identical.
|
|
56
|
+
*/
|
|
57
|
+
export const USER_AGENT = "crewhaus-tool-kyc (+https://github.com/crewhaus/factory)";
|
|
58
|
+
export const DEFAULT_TIMEOUT_MS = 20_000;
|
|
59
|
+
export const MAX_TIMEOUT_MS = 120_000;
|
|
60
|
+
export const MAX_REDIRECTS = 3;
|
|
61
|
+
/**
|
|
62
|
+
* 8 MB. An EDGAR submissions document for a frequent filer genuinely runs to
|
|
63
|
+
* megabytes and the ticker map is over a megabyte on its own; this is memory,
|
|
64
|
+
* not context, since only a handful of fields is ever returned.
|
|
65
|
+
*/
|
|
66
|
+
export const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
|
|
67
|
+
/** Compact JSON — every byte returned is a byte in somebody's context window. */
|
|
68
|
+
export const json = (value) => JSON.stringify(value);
|
|
69
|
+
/**
|
|
70
|
+
* Dial the vetted IP while keeping the real hostname for the `Host` header and
|
|
71
|
+
* TLS SNI. Carried over from `tool-fetch`'s own dialler rather than
|
|
72
|
+
* re-derived: resolving in the guard and letting `fetch` resolve again at
|
|
73
|
+
* connect time is a DNS-rebinding TOCTOU, so the pin has to be applied by
|
|
74
|
+
* whoever makes the request.
|
|
75
|
+
*
|
|
76
|
+
* This function and `guardedFetch` are the two things in this package no test
|
|
77
|
+
* executes, because executing them means opening a socket. That is the point
|
|
78
|
+
* of putting the seam above them.
|
|
79
|
+
*/
|
|
80
|
+
function pinnedFetch(req, pinnedIp) {
|
|
81
|
+
const original = new URL(req.url);
|
|
82
|
+
const host = original.hostname;
|
|
83
|
+
if (pinnedIp === "" || host === pinnedIp)
|
|
84
|
+
return globalThis.fetch(req);
|
|
85
|
+
const pinnedUrl = new URL(original.toString());
|
|
86
|
+
pinnedUrl.hostname = pinnedIp.includes(":") ? `[${pinnedIp}]` : pinnedIp;
|
|
87
|
+
const headers = new Headers(req.headers);
|
|
88
|
+
headers.set("host", original.port === "" ? host : `${host}:${original.port}`);
|
|
89
|
+
const init = {
|
|
90
|
+
method: req.method,
|
|
91
|
+
headers,
|
|
92
|
+
redirect: "manual",
|
|
93
|
+
signal: req.signal,
|
|
94
|
+
tls: { serverName: host },
|
|
95
|
+
};
|
|
96
|
+
return globalThis.fetch(pinnedUrl.toString(), init);
|
|
97
|
+
}
|
|
98
|
+
const guardedFetch = async (req) => {
|
|
99
|
+
const url = new URL(req.url);
|
|
100
|
+
const pinnedIp = await assertNotSsrf(url.hostname);
|
|
101
|
+
return pinnedFetch(req, pinnedIp);
|
|
102
|
+
};
|
|
103
|
+
let kycFetch = guardedFetch;
|
|
104
|
+
/**
|
|
105
|
+
* Test-only injection point, the convention every networked package here
|
|
106
|
+
* follows. `undefined` restores the guarded dialler; a suite that sets it must
|
|
107
|
+
* restore it, or the next file in the same bun process inherits the stub.
|
|
108
|
+
*/
|
|
109
|
+
export function _setKycFetch(fn) {
|
|
110
|
+
kycFetch = fn ?? guardedFetch;
|
|
111
|
+
}
|
|
112
|
+
/** The kinds that mean "could not check", i.e. everything except `notFound`. */
|
|
113
|
+
export function isUnavailable(kind) {
|
|
114
|
+
return kind !== "notFound";
|
|
115
|
+
}
|
|
116
|
+
function assertKnownOrigin(url) {
|
|
117
|
+
if (!ALLOWED_ORIGINS.has(url.origin)) {
|
|
118
|
+
throw new KycNetworkError(`refusing to dial "${url.origin}" — this package only reaches ${[...ALLOWED_ORIGINS].join(", ")}`);
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* GET a JSON document from one of the registers above.
|
|
123
|
+
*
|
|
124
|
+
* Failures are RETURNED rather than thrown: a caller reading four registers
|
|
125
|
+
* wants a row saying what went wrong with one of them, not to lose the other
|
|
126
|
+
* three. The one exception is a URL whose origin is not ours, which is a
|
|
127
|
+
* defect in this package and throws.
|
|
128
|
+
*/
|
|
129
|
+
export async function getJson(rawUrl, options = {}) {
|
|
130
|
+
let current;
|
|
131
|
+
try {
|
|
132
|
+
current = new URL(rawUrl);
|
|
133
|
+
}
|
|
134
|
+
catch {
|
|
135
|
+
throw new KycNetworkError(`built an invalid URL: "${rawUrl}"`);
|
|
136
|
+
}
|
|
137
|
+
assertKnownOrigin(current);
|
|
138
|
+
const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
|
|
139
|
+
const isPost = options.postJson !== undefined;
|
|
140
|
+
const headers = {
|
|
141
|
+
accept: options.accept ?? "application/json",
|
|
142
|
+
"user-agent": USER_AGENT,
|
|
143
|
+
...(isPost ? { "content-type": "application/json" } : {}),
|
|
144
|
+
};
|
|
145
|
+
for (let hop = 0;; hop++) {
|
|
146
|
+
let res;
|
|
147
|
+
try {
|
|
148
|
+
const init = {
|
|
149
|
+
method: isPost ? "POST" : "GET",
|
|
150
|
+
redirect: "manual",
|
|
151
|
+
headers,
|
|
152
|
+
...(isPost ? { body: JSON.stringify(options.postJson) } : {}),
|
|
153
|
+
};
|
|
154
|
+
if (options.signal !== undefined)
|
|
155
|
+
init.signal = options.signal;
|
|
156
|
+
res = await kycFetch(new Request(current.toString(), init));
|
|
157
|
+
}
|
|
158
|
+
catch (err) {
|
|
159
|
+
if (err instanceof KycNetworkError)
|
|
160
|
+
return { ok: false, kind: "refused", message: err.message };
|
|
161
|
+
const error = err;
|
|
162
|
+
if (error?.name === "FetchPermissionError") {
|
|
163
|
+
// What `assertNotSsrf` throws when the name resolved somewhere it will
|
|
164
|
+
// not dial. A refusal, not a transport failure: retrying is exactly
|
|
165
|
+
// what will not help.
|
|
166
|
+
return { ok: false, kind: "refused", message: error.message };
|
|
167
|
+
}
|
|
168
|
+
if (error?.name === "AbortError" || options.signal?.aborted === true) {
|
|
169
|
+
return {
|
|
170
|
+
ok: false,
|
|
171
|
+
kind: "transport",
|
|
172
|
+
message: `the deadline elapsed before ${safeLabel(current)} answered`,
|
|
173
|
+
};
|
|
174
|
+
}
|
|
175
|
+
return {
|
|
176
|
+
ok: false,
|
|
177
|
+
kind: "transport",
|
|
178
|
+
message: `could not reach ${safeLabel(current)}: ${error?.message ?? String(err)}`,
|
|
179
|
+
};
|
|
180
|
+
}
|
|
181
|
+
if (res.status >= 300 && res.status < 400 && res.headers.has("location")) {
|
|
182
|
+
const location = res.headers.get("location") ?? "";
|
|
183
|
+
await discard(res);
|
|
184
|
+
if (isPost) {
|
|
185
|
+
// A 307/308 re-sends the body and a 302 silently turns it into a GET;
|
|
186
|
+
// neither is something to do on the caller's behalf when the body
|
|
187
|
+
// carries the requester's own VAT id. One endpoint, no redirects.
|
|
188
|
+
return {
|
|
189
|
+
ok: false,
|
|
190
|
+
kind: "refused",
|
|
191
|
+
message: `${safeLabel(current)} redirected a POST to "${location}" — this package does not re-send a body to a new location`,
|
|
192
|
+
};
|
|
193
|
+
}
|
|
194
|
+
if (hop >= MAX_REDIRECTS) {
|
|
195
|
+
return {
|
|
196
|
+
ok: false,
|
|
197
|
+
kind: "refused",
|
|
198
|
+
message: `too many redirects (>${MAX_REDIRECTS}) from ${safeLabel(current)}`,
|
|
199
|
+
};
|
|
200
|
+
}
|
|
201
|
+
let next;
|
|
202
|
+
try {
|
|
203
|
+
next = new URL(location, current);
|
|
204
|
+
}
|
|
205
|
+
catch {
|
|
206
|
+
return { ok: false, kind: "refused", message: `invalid redirect target "${location}"` };
|
|
207
|
+
}
|
|
208
|
+
if (!ALLOWED_ORIGINS.has(next.origin)) {
|
|
209
|
+
return {
|
|
210
|
+
ok: false,
|
|
211
|
+
kind: "refused",
|
|
212
|
+
message: `refusing a redirect from ${safeLabel(current)} to "${next.origin}" — outside the registers this package reads`,
|
|
213
|
+
};
|
|
214
|
+
}
|
|
215
|
+
current = next;
|
|
216
|
+
continue;
|
|
217
|
+
}
|
|
218
|
+
if (res.status === 404 || res.status === 410) {
|
|
219
|
+
await discard(res);
|
|
220
|
+
return {
|
|
221
|
+
ok: false,
|
|
222
|
+
kind: "notFound",
|
|
223
|
+
status: res.status,
|
|
224
|
+
message: `${safeLabel(current)} answered ${res.status}`,
|
|
225
|
+
};
|
|
226
|
+
}
|
|
227
|
+
if (res.status === 401 || res.status === 403) {
|
|
228
|
+
await discard(res);
|
|
229
|
+
// These are open-access endpoints, so this means something changed at
|
|
230
|
+
// their end (or a proxy is in the way). It is emphatically NOT evidence
|
|
231
|
+
// about the subject, and a tool that read it as "not registered" would
|
|
232
|
+
// be inventing a legal fact out of an access-control response.
|
|
233
|
+
return {
|
|
234
|
+
ok: false,
|
|
235
|
+
kind: "unauthorized",
|
|
236
|
+
status: res.status,
|
|
237
|
+
message: `${safeLabel(current)} answered ${res.status} — this tool holds no credential for it, so the register could not be read`,
|
|
238
|
+
};
|
|
239
|
+
}
|
|
240
|
+
if (res.status === 429) {
|
|
241
|
+
await discard(res);
|
|
242
|
+
const retryAfter = res.headers.get("retry-after") ?? undefined;
|
|
243
|
+
return {
|
|
244
|
+
ok: false,
|
|
245
|
+
kind: "rateLimited",
|
|
246
|
+
status: 429,
|
|
247
|
+
message: `${safeLabel(current)} rate-limited this read${retryAfter === undefined ? "" : `; it asked for ${retryAfter}s`} — this package does not retry, so the caller decides when to ask again`,
|
|
248
|
+
...(retryAfter === undefined ? {} : { retryAfter }),
|
|
249
|
+
};
|
|
250
|
+
}
|
|
251
|
+
if (!res.ok) {
|
|
252
|
+
await discard(res);
|
|
253
|
+
return {
|
|
254
|
+
ok: false,
|
|
255
|
+
kind: "status",
|
|
256
|
+
status: res.status,
|
|
257
|
+
message: `${safeLabel(current)} answered ${res.status} ${res.statusText}`.trimEnd(),
|
|
258
|
+
};
|
|
259
|
+
}
|
|
260
|
+
const body = await readCapped(res, maxBytes);
|
|
261
|
+
if (body.truncated) {
|
|
262
|
+
// Parsing the prefix is the tempting mistake: half an EDGAR submissions
|
|
263
|
+
// document still parses into a shorter, plausible, WRONG answer.
|
|
264
|
+
return {
|
|
265
|
+
ok: false,
|
|
266
|
+
kind: "tooLarge",
|
|
267
|
+
status: res.status,
|
|
268
|
+
message: `the document at ${safeLabel(current)} is larger than the ${maxBytes}-byte cap — refusing to answer from a prefix of it`,
|
|
269
|
+
};
|
|
270
|
+
}
|
|
271
|
+
try {
|
|
272
|
+
return { ok: true, value: JSON.parse(body.text), status: res.status, bytes: body.bytes };
|
|
273
|
+
}
|
|
274
|
+
catch (err) {
|
|
275
|
+
return {
|
|
276
|
+
ok: false,
|
|
277
|
+
kind: "malformed",
|
|
278
|
+
status: res.status,
|
|
279
|
+
message: `${safeLabel(current)} answered ${body.bytes} bytes that are not JSON: ${err.message}`,
|
|
280
|
+
};
|
|
281
|
+
}
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
/** Scheme, host and path — never the query, which can carry a subject's name. */
|
|
285
|
+
export function safeLabel(url) {
|
|
286
|
+
try {
|
|
287
|
+
const parsed = typeof url === "string" ? new URL(url) : url;
|
|
288
|
+
return `${parsed.origin}${parsed.pathname}`;
|
|
289
|
+
}
|
|
290
|
+
catch {
|
|
291
|
+
return String(url);
|
|
292
|
+
}
|
|
293
|
+
}
|
|
294
|
+
async function discard(res) {
|
|
295
|
+
try {
|
|
296
|
+
await res.body?.cancel();
|
|
297
|
+
}
|
|
298
|
+
catch {
|
|
299
|
+
// already closed — nothing to release
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
/**
|
|
303
|
+
* Drain a body with a hard byte cap, cancelling the stream the moment the cap
|
|
304
|
+
* is passed. The cap bounds MEMORY, not just what is kept.
|
|
305
|
+
*/
|
|
306
|
+
export async function readCapped(res, maxBytes) {
|
|
307
|
+
if (res.body === null) {
|
|
308
|
+
const text = await res.text();
|
|
309
|
+
const bytes = new TextEncoder().encode(text).byteLength;
|
|
310
|
+
return bytes > maxBytes
|
|
311
|
+
? { text: "", bytes, truncated: true }
|
|
312
|
+
: { text, bytes, truncated: false };
|
|
313
|
+
}
|
|
314
|
+
const reader = res.body.getReader();
|
|
315
|
+
const chunks = [];
|
|
316
|
+
let total = 0;
|
|
317
|
+
let truncated = false;
|
|
318
|
+
try {
|
|
319
|
+
while (true) {
|
|
320
|
+
const { done, value } = await reader.read();
|
|
321
|
+
if (done || value === undefined)
|
|
322
|
+
break;
|
|
323
|
+
if (total + value.byteLength > maxBytes) {
|
|
324
|
+
truncated = true;
|
|
325
|
+
try {
|
|
326
|
+
await reader.cancel();
|
|
327
|
+
}
|
|
328
|
+
catch {
|
|
329
|
+
// already aborting
|
|
330
|
+
}
|
|
331
|
+
break;
|
|
332
|
+
}
|
|
333
|
+
chunks.push(value);
|
|
334
|
+
total += value.byteLength;
|
|
335
|
+
}
|
|
336
|
+
}
|
|
337
|
+
finally {
|
|
338
|
+
try {
|
|
339
|
+
reader.releaseLock();
|
|
340
|
+
}
|
|
341
|
+
catch {
|
|
342
|
+
// already released
|
|
343
|
+
}
|
|
344
|
+
}
|
|
345
|
+
if (truncated)
|
|
346
|
+
return { text: "", bytes: total, truncated: true };
|
|
347
|
+
const merged = new Uint8Array(total);
|
|
348
|
+
let offset = 0;
|
|
349
|
+
for (const chunk of chunks) {
|
|
350
|
+
merged.set(chunk, offset);
|
|
351
|
+
offset += chunk.byteLength;
|
|
352
|
+
}
|
|
353
|
+
return {
|
|
354
|
+
text: new TextDecoder("utf-8", { fatal: false }).decode(merged),
|
|
355
|
+
bytes: total,
|
|
356
|
+
truncated: false,
|
|
357
|
+
};
|
|
358
|
+
}
|
|
359
|
+
/**
|
|
360
|
+
* A deadline that also honours the runtime's own cancellation. Every tool here
|
|
361
|
+
* opens one before its first byte and cancels it in a `finally`: VIES in
|
|
362
|
+
* particular can hang for a member state that is half up, and a tool that
|
|
363
|
+
* hangs forever is worse than one that reports `unavailable`.
|
|
364
|
+
*/
|
|
365
|
+
export function startDeadline(ms, outer) {
|
|
366
|
+
const ctrl = new AbortController();
|
|
367
|
+
const timer = setTimeout(() => ctrl.abort(new Error(`deadline of ${ms}ms elapsed`)), ms);
|
|
368
|
+
const onOuter = () => ctrl.abort(outer?.reason);
|
|
369
|
+
if (outer !== undefined) {
|
|
370
|
+
if (outer.aborted)
|
|
371
|
+
ctrl.abort(outer.reason);
|
|
372
|
+
else
|
|
373
|
+
outer.addEventListener("abort", onOuter, { once: true });
|
|
374
|
+
}
|
|
375
|
+
return {
|
|
376
|
+
signal: ctrl.signal,
|
|
377
|
+
cancel: () => {
|
|
378
|
+
clearTimeout(timer);
|
|
379
|
+
outer?.removeEventListener("abort", onOuter);
|
|
380
|
+
},
|
|
381
|
+
};
|
|
382
|
+
}
|
|
383
|
+
/**
|
|
384
|
+
* An instant, as an ISO-8601 string WITH an offset.
|
|
385
|
+
*
|
|
386
|
+
* Offset-less strings are refused: per ECMAScript they mean local time, so the
|
|
387
|
+
* same evidence record would carry a different day on two machines — and the
|
|
388
|
+
* day a screening ran is the part of the record that matters later.
|
|
389
|
+
*/
|
|
390
|
+
export function parseInstant(value, field) {
|
|
391
|
+
const text = value.trim();
|
|
392
|
+
if (!/(?:Z|[+-]\d{2}:?\d{2})$/i.test(text)) {
|
|
393
|
+
throw new Error(`${field} ("${text}") has no UTC offset — write it as e.g. 2026-01-01T00:00:00Z, because an offset-less string means local time and would differ between machines`);
|
|
394
|
+
}
|
|
395
|
+
const parsed = Date.parse(text);
|
|
396
|
+
if (Number.isNaN(parsed))
|
|
397
|
+
throw new Error(`${field} ("${text}") is not a valid ISO-8601 instant`);
|
|
398
|
+
return parsed;
|
|
399
|
+
}
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Sanctions screening: candidates and evidence, never a verdict.
|
|
3
|
+
*
|
|
4
|
+
* Three decisions shape this file, and all three are deliberate departures
|
|
5
|
+
* from what a screening tool is usually asked for.
|
|
6
|
+
*
|
|
7
|
+
* 1. **No verdict.** A sanctions match is a legal determination with legal
|
|
8
|
+
* consequences, and it is made by a person. This returns the candidates it
|
|
9
|
+
* found, the basis for each one, and the version of every list it read. The
|
|
10
|
+
* shipped precedent is `@crewhaus/tool-money`'s `RefundAbuseCheck`, which
|
|
11
|
+
* returns ratios and counts and says "a person decides" — same reasoning,
|
|
12
|
+
* higher stakes.
|
|
13
|
+
*
|
|
14
|
+
* 2. **The evidence is the product.** The score is the least trustworthy thing
|
|
15
|
+
* here: the lists carry transliterations of names that were never written in
|
|
16
|
+
* the Latin alphabet, and aliases the publisher itself marks as low quality.
|
|
17
|
+
* What survives an audit two years later is not "0.87", it is "screened
|
|
18
|
+
* against OFAC SDN version 20260901, published 2026-09-01, retrieved
|
|
19
|
+
* 2026-09-02". So a list that cannot say what version it is gets REFUSED,
|
|
20
|
+
* and the whole screen fails rather than quietly producing a number.
|
|
21
|
+
*
|
|
22
|
+
* 3. **Nothing leaves the machine.** Screening happens locally against a
|
|
23
|
+
* snapshot the operator holds. A counterparty's name sent to a third-party
|
|
24
|
+
* screening API is a disclosure of who you are about to pay, to somebody who
|
|
25
|
+
* did not need to know — and this package has no endpoint for it.
|
|
26
|
+
*/
|
|
27
|
+
import { type TokenAlignment } from "./names";
|
|
28
|
+
export type AliasQuality = "strong" | "weak";
|
|
29
|
+
export type ListAlias = {
|
|
30
|
+
readonly name: string;
|
|
31
|
+
/**
|
|
32
|
+
* The publisher's own quality mark. OFAC publishes "weak" aliases — partial
|
|
33
|
+
* names, nicknames, spellings it is not confident in — and says in its own
|
|
34
|
+
* guidance that a weak-alias hit alone is not a reason to act.
|
|
35
|
+
*/
|
|
36
|
+
readonly quality?: AliasQuality;
|
|
37
|
+
};
|
|
38
|
+
export type ListEntry = {
|
|
39
|
+
readonly id: string;
|
|
40
|
+
readonly name: string;
|
|
41
|
+
readonly kind?: "person" | "entity" | "vessel" | "aircraft" | "unknown";
|
|
42
|
+
readonly aliases?: ReadonlyArray<ListAlias>;
|
|
43
|
+
readonly countries?: ReadonlyArray<string>;
|
|
44
|
+
readonly datesOfBirth?: ReadonlyArray<string>;
|
|
45
|
+
readonly programs?: ReadonlyArray<string>;
|
|
46
|
+
readonly remarks?: string;
|
|
47
|
+
};
|
|
48
|
+
export type ListSnapshot = {
|
|
49
|
+
/** The publisher and list, e.g. "OFAC SDN". */
|
|
50
|
+
readonly source: string;
|
|
51
|
+
/** The publisher's own version or issue id. Required. */
|
|
52
|
+
readonly version: string;
|
|
53
|
+
/** When the publisher published it. Required, ISO-8601 with an offset. */
|
|
54
|
+
readonly publishedAt: string;
|
|
55
|
+
/** When this copy was taken. Required, ISO-8601 with an offset. */
|
|
56
|
+
readonly retrievedAt: string;
|
|
57
|
+
readonly sourceUrl?: string;
|
|
58
|
+
readonly entries: ReadonlyArray<ListEntry>;
|
|
59
|
+
};
|
|
60
|
+
export type Subject = {
|
|
61
|
+
readonly id: string;
|
|
62
|
+
readonly name: string;
|
|
63
|
+
readonly aliases?: ReadonlyArray<string>;
|
|
64
|
+
readonly kind?: "person" | "entity";
|
|
65
|
+
readonly country?: string;
|
|
66
|
+
readonly dateOfBirth?: string;
|
|
67
|
+
};
|
|
68
|
+
export type ScreenPolicy = {
|
|
69
|
+
/** The score at or above which a candidate is reported. */
|
|
70
|
+
readonly threshold: number;
|
|
71
|
+
/** How many candidates to report per subject. */
|
|
72
|
+
readonly limit: number;
|
|
73
|
+
readonly includeWeakAliases: boolean;
|
|
74
|
+
};
|
|
75
|
+
/**
|
|
76
|
+
* The first pass is a FILTER, not a score.
|
|
77
|
+
*
|
|
78
|
+
* It is set loose on purpose: the whole-string comparison and the weighted
|
|
79
|
+
* token comparison disagree, and the token pass routinely raises a pair the
|
|
80
|
+
* string pass scored 0.6 — that is the entire reason the token pass exists.
|
|
81
|
+
* Filtering at the reporting threshold would throw those away before they were
|
|
82
|
+
* scored properly.
|
|
83
|
+
*
|
|
84
|
+
* A loose floor is NOT enough on its own, which cost this file a false clean.
|
|
85
|
+
* Jaro-Winkler scores "kharoubi" against "mohammed kharoubi" at 0.35 — no
|
|
86
|
+
* usable floor is below that — because its prefix bonus rewards names that
|
|
87
|
+
* begin alike, so a subject supplied as a surname scored 0.35 and a subject
|
|
88
|
+
* supplied as the same person's given name scored 0.89. Screening by surname
|
|
89
|
+
* returned no candidate, no near miss and no truncation flag, on a person who
|
|
90
|
+
* was on the list. Containment is exactly what the two-direction token scorer
|
|
91
|
+
* below exists to handle, and it never ran, because the name never reached it.
|
|
92
|
+
* So the shortlist is a UNION of this pass and `shortlistByToken`.
|
|
93
|
+
*/
|
|
94
|
+
export declare const PREFILTER_FLOOR = 0.5;
|
|
95
|
+
/** How many survivors per subject go through to the expensive pass, per pass. */
|
|
96
|
+
export declare const PREFILTER_WIDTH = 5;
|
|
97
|
+
export type Corroboration = {
|
|
98
|
+
readonly country: string;
|
|
99
|
+
readonly dateOfBirth: string;
|
|
100
|
+
/**
|
|
101
|
+
* Always false. Most list entries carry neither a country nor a date of
|
|
102
|
+
* birth, so letting a mismatch lower a score would clear true hits for the
|
|
103
|
+
* entries that are least complete — which are the older and more serious
|
|
104
|
+
* ones. Corroboration is for the human reading the candidate.
|
|
105
|
+
*/
|
|
106
|
+
readonly usedForScoring: false;
|
|
107
|
+
};
|
|
108
|
+
export type Candidate = {
|
|
109
|
+
readonly list: string;
|
|
110
|
+
readonly listVersion: string;
|
|
111
|
+
readonly entryId: string;
|
|
112
|
+
readonly entryName: string;
|
|
113
|
+
readonly entryKind: string;
|
|
114
|
+
readonly matchedName: string;
|
|
115
|
+
readonly matchedOn: "primary" | "alias";
|
|
116
|
+
readonly aliasQuality: AliasQuality;
|
|
117
|
+
readonly score: number;
|
|
118
|
+
readonly scoreForward: number;
|
|
119
|
+
readonly scoreReverse: number;
|
|
120
|
+
readonly scoreWholeString: number;
|
|
121
|
+
readonly alignments: ReadonlyArray<TokenAlignment>;
|
|
122
|
+
readonly droppedSuffixes: ReadonlyArray<string>;
|
|
123
|
+
readonly corroboration: Corroboration;
|
|
124
|
+
readonly programs: ReadonlyArray<string>;
|
|
125
|
+
};
|
|
126
|
+
export type SubjectResult = {
|
|
127
|
+
readonly subjectId: string;
|
|
128
|
+
readonly name: string;
|
|
129
|
+
readonly canonical: string;
|
|
130
|
+
readonly namesCompared: number;
|
|
131
|
+
readonly shortlisted: number;
|
|
132
|
+
readonly candidates: ReadonlyArray<Candidate>;
|
|
133
|
+
/** Weak-alias hits, kept apart on purpose. */
|
|
134
|
+
readonly weakAliasCandidates: ReadonlyArray<Candidate>;
|
|
135
|
+
/** The best score that did NOT reach the threshold, or null if there was none. */
|
|
136
|
+
readonly bestScoreBelowThreshold: number | null;
|
|
137
|
+
readonly note?: string;
|
|
138
|
+
/** True when the first pass filled its cap, so lower-scoring names were not re-scored. */
|
|
139
|
+
readonly prefilterTruncated?: boolean;
|
|
140
|
+
};
|
|
141
|
+
export type ListEvidence = {
|
|
142
|
+
readonly source: string;
|
|
143
|
+
readonly version: string;
|
|
144
|
+
readonly publishedAt: string;
|
|
145
|
+
readonly retrievedAt: string;
|
|
146
|
+
readonly sourceUrl?: string;
|
|
147
|
+
readonly entries: number;
|
|
148
|
+
readonly names: number;
|
|
149
|
+
readonly ageDays: number;
|
|
150
|
+
};
|
|
151
|
+
export type ScreenResult = {
|
|
152
|
+
readonly evidence: {
|
|
153
|
+
readonly screenedAt: string;
|
|
154
|
+
readonly lists: ReadonlyArray<ListEvidence>;
|
|
155
|
+
readonly policy: ScreenPolicy & {
|
|
156
|
+
readonly matcher: string;
|
|
157
|
+
readonly normalisation: string;
|
|
158
|
+
};
|
|
159
|
+
};
|
|
160
|
+
readonly subjects: ReadonlyArray<SubjectResult>;
|
|
161
|
+
readonly note: string;
|
|
162
|
+
};
|
|
163
|
+
/** Why a snapshot cannot be screened against. Returned, not thrown. */
|
|
164
|
+
export type SnapshotRefusal = {
|
|
165
|
+
readonly list: string;
|
|
166
|
+
readonly reason: string;
|
|
167
|
+
};
|
|
168
|
+
/**
|
|
169
|
+
* Check a snapshot carries the evidence a screening needs to be worth anything.
|
|
170
|
+
*
|
|
171
|
+
* A list with no version is not a cheaper list, it is an unusable one: the
|
|
172
|
+
* result it produces cannot be reproduced, defended or dated. The staleness
|
|
173
|
+
* check is the same argument in the other direction — "no matches" against a
|
|
174
|
+
* list from March is a sentence about March.
|
|
175
|
+
*/
|
|
176
|
+
export declare function checkSnapshot(snapshot: ListSnapshot, nowMs: number, maxAgeDays: number): SnapshotRefusal | {
|
|
177
|
+
readonly ageDays: number;
|
|
178
|
+
};
|
|
179
|
+
/**
|
|
180
|
+
* Screen every subject against every list.
|
|
181
|
+
*
|
|
182
|
+
* The clock is a parameter. A screening record that says when it ran is only
|
|
183
|
+
* worth something if the "when" is the same on the machine that ran it and the
|
|
184
|
+
* machine that replays it.
|
|
185
|
+
*/
|
|
186
|
+
export declare function screenSubjects(subjects: ReadonlyArray<Subject>, snapshots: ReadonlyArray<ListSnapshot>, ages: ReadonlyArray<number>, policy: ScreenPolicy, nowMs: number): Promise<ScreenResult>;
|