@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/README.md
ADDED
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
# @crewhaus/tool-kyc
|
|
2
|
+
|
|
3
|
+
Checking who you are about to pay or invoice, against public registers and
|
|
4
|
+
sanctions lists, with evidence you can still read a year later.
|
|
5
|
+
|
|
6
|
+
| Tool | Answers |
|
|
7
|
+
|---|---|
|
|
8
|
+
| `VatIdValidate` | is this VAT number real, whose is it, and what is the receipt |
|
|
9
|
+
| `EntityRegistryLookup` | what do GLEIF and SEC EDGAR say about this company |
|
|
10
|
+
| `SanctionsScreen` | which list entries look like this name, and on what basis |
|
|
11
|
+
|
|
12
|
+
## Three outcomes, not two
|
|
13
|
+
|
|
14
|
+
Every tool here reports **found**, **not-found** or **could-not-check**, and
|
|
15
|
+
the third one says why. There is no `valid` boolean anywhere in this package,
|
|
16
|
+
because a boolean has two values and this has three — and the collapse always
|
|
17
|
+
goes the same way.
|
|
18
|
+
|
|
19
|
+
It matters most at VIES. VIES does not hold the data; it forwards the question
|
|
20
|
+
to each member state's own system, and those systems go down individually, for
|
|
21
|
+
hours, routinely. VIES reports that as a service code with `isValid: false`
|
|
22
|
+
alongside it. A tool that reads the boolean gets "this VAT number is not
|
|
23
|
+
valid", and a harness then charges domestic VAT on an intra-community supply —
|
|
24
|
+
or refuses to zero-rate an invoice — because a government server was being
|
|
25
|
+
rebooted.
|
|
26
|
+
|
|
27
|
+
So every code VIES publishes is mapped explicitly, and a code we have never
|
|
28
|
+
seen becomes *could-not-check* with the code quoted, rather than a guess about
|
|
29
|
+
which side of the line it falls on. The same rule covers HTTP: a 500, a 429 or
|
|
30
|
+
a 403 is *could-not-check*. The only 404 that means anything about the subject
|
|
31
|
+
is HMRC's, which is documented to mean "not registered".
|
|
32
|
+
|
|
33
|
+
`syntaxOnly` fits the same grammar: the format is well-formed, and registration
|
|
34
|
+
reads as unchecked rather than as fine.
|
|
35
|
+
|
|
36
|
+
## SanctionsScreen returns signals and evidence, never a verdict
|
|
37
|
+
|
|
38
|
+
A sanctions match is a legal determination with legal consequences, and a
|
|
39
|
+
person makes it. This tool surfaces candidates, the basis for each, and the
|
|
40
|
+
version of every list it read.
|
|
41
|
+
|
|
42
|
+
That follows `@crewhaus/tool-money`, whose controls return signals and let the
|
|
43
|
+
caller decide — its refund check returns ratios and `null` rather than a
|
|
44
|
+
fabricated infinity, and says a person decides. The catalogue asked for a
|
|
45
|
+
score here; the shipped convention won.
|
|
46
|
+
|
|
47
|
+
**The evidence is the product.** The score is the least trustworthy part of the
|
|
48
|
+
answer: the lists carry transliterations of names never written in the Latin
|
|
49
|
+
alphabet, and aliases the publishers themselves mark as weak. What survives an
|
|
50
|
+
audit is not `0.87`, it is "OFAC SDN, version 20260917, published 2026-09-17,
|
|
51
|
+
retrieved 2026-09-17". So:
|
|
52
|
+
|
|
53
|
+
- `version`, `publishedAt` and `retrievedAt` are **required** on every
|
|
54
|
+
snapshot, and a missing one refuses the screen rather than scoring it.
|
|
55
|
+
- A list older than `maxAgeDays` (30 by default) refuses the screen. "No
|
|
56
|
+
matches" against a list from March is a sentence about March.
|
|
57
|
+
- A snapshot published after it was retrieved, or retrieved after the screen
|
|
58
|
+
ran, refuses as well. Age is clamped at zero, so a mistyped year would
|
|
59
|
+
otherwise report `ageDays: 0` and turn the freshness gate off permanently —
|
|
60
|
+
a control that cannot be evaluated must not count as one that held.
|
|
61
|
+
- An empty list refuses too, because empty reads exactly like clean.
|
|
62
|
+
- One unusable list refuses the **whole** screen. Screening against the other
|
|
63
|
+
three and reporting no candidates would be an answer with a hole in it that
|
|
64
|
+
nothing in the output would show.
|
|
65
|
+
- No candidate over the threshold is reported as *not a clearance*, with the
|
|
66
|
+
best near miss beside it.
|
|
67
|
+
|
|
68
|
+
Weak aliases are scored into their own bucket and never mixed in. Country and
|
|
69
|
+
date of birth corroborate for the person reading the result and never change a
|
|
70
|
+
score: most entries carry neither, so a mismatch would clear hardest on the
|
|
71
|
+
least complete — and oldest — entries.
|
|
72
|
+
|
|
73
|
+
**Nothing leaves the machine.** Screening runs against a snapshot you hold.
|
|
74
|
+
Sending a counterparty's name to a screening API discloses who you are about to
|
|
75
|
+
pay to somebody who did not need to know, and this tool has no endpoint to
|
|
76
|
+
disclose it to. The suite asserts that it never dials.
|
|
77
|
+
|
|
78
|
+
A snapshot is JSON:
|
|
79
|
+
|
|
80
|
+
```json
|
|
81
|
+
{
|
|
82
|
+
"source": "OFAC SDN",
|
|
83
|
+
"version": "20260917",
|
|
84
|
+
"publishedAt": "2026-09-17T00:00:00Z",
|
|
85
|
+
"retrievedAt": "2026-09-17T06:00:00Z",
|
|
86
|
+
"entries": [
|
|
87
|
+
{
|
|
88
|
+
"id": "SDN-1",
|
|
89
|
+
"name": "Mohammed Kharoubi",
|
|
90
|
+
"kind": "person",
|
|
91
|
+
"aliases": [{ "name": "Abu Mohammed", "quality": "weak" }],
|
|
92
|
+
"countries": ["SY"],
|
|
93
|
+
"programs": ["SDGT"]
|
|
94
|
+
}
|
|
95
|
+
]
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Refreshing it from the publishers is the operator's own step, and deliberately
|
|
100
|
+
outside this package — see *What this package does not do*.
|
|
101
|
+
|
|
102
|
+
## One matcher, not two
|
|
103
|
+
|
|
104
|
+
Jaro-Winkler, the token comparison and the Unicode hygiene come from
|
|
105
|
+
`@crewhaus/tool-text` — this package calls its `FuzzyMatch` and `NormalizeText`
|
|
106
|
+
tools rather than carrying a second copy, the way `@crewhaus/tool-token` calls
|
|
107
|
+
`tool-onchain` for EIP-55. Two matchers would be two answers to "how close are
|
|
108
|
+
these names", and they would disagree exactly where it costs most.
|
|
109
|
+
|
|
110
|
+
What this package adds is the part that is specific to names on a list:
|
|
111
|
+
|
|
112
|
+
- **Folding that a diff must not do.** Diacritics are folded, and so are the
|
|
113
|
+
letters NFD cannot decompose (ø, đ, ł, æ, ß). For a diff, "resume" and
|
|
114
|
+
"résumé" are two different files; for a name they are one person.
|
|
115
|
+
- **Legal forms dropped from company names**, and recorded — counting "ltd" as
|
|
116
|
+
a shared token inflates every comparison between two British companies.
|
|
117
|
+
- **Token weighting from the lists themselves.** On a list where half the
|
|
118
|
+
entries contain "mohammed", matching that token is worth almost nothing and a
|
|
119
|
+
rare surname is worth almost everything. A flat token-set ratio scores them
|
|
120
|
+
equally, which is what floods a queue with false positives on common given
|
|
121
|
+
names while still missing the transliteration pairs.
|
|
122
|
+
- **Both directions.** A one-token subject aligns perfectly *into* any entry
|
|
123
|
+
containing that token, so the entry's unmatched tokens have to cost something
|
|
124
|
+
too.
|
|
125
|
+
- **A shortlist that can see containment.** The cheap first pass is a
|
|
126
|
+
whole-string comparison, and Jaro-Winkler rewards a shared prefix: "Mohammed"
|
|
127
|
+
against "Mohammed Kharoubi" scores 0.89 and "Kharoubi" against the same entry
|
|
128
|
+
scores 0.35. A shortlist built on that alone answered "no candidates, no near
|
|
129
|
+
miss" for a subject typed as his surname. So it is a union — whole-string
|
|
130
|
+
similarity **plus** every entry sharing a token with the subject, rarest
|
|
131
|
+
token first — and when the union fills its cap the result says so, in the
|
|
132
|
+
note as well as in `prefilterTruncated`.
|
|
133
|
+
- **Invisible characters reported, not just removed.** A zero-width joiner
|
|
134
|
+
inside a supplied name is how a name misses a list it should hit.
|
|
135
|
+
|
|
136
|
+
Every candidate carries which tokens aligned with which, and at what weight.
|
|
137
|
+
That is the match basis, and it is the part a reviewer can actually check.
|
|
138
|
+
|
|
139
|
+
## Two registers, never merged
|
|
140
|
+
|
|
141
|
+
`EntityRegistryLookup` returns one row per register, each with its own source
|
|
142
|
+
URL and retrieval time. It does not produce one confident record, because the
|
|
143
|
+
registers disagree about all of it — name spellings, suffixes, accents, number
|
|
144
|
+
formats — and above all about status:
|
|
145
|
+
|
|
146
|
+
- GLEIF's `entity.status` answers "is the company still there".
|
|
147
|
+
- GLEIF's `registration.status` answers "is the LEI paid up".
|
|
148
|
+
|
|
149
|
+
A LAPSED registration is overwhelmingly an unpaid renewal on a trading company.
|
|
150
|
+
Folding that into `dissolved` would hold a payment to a live supplier over a
|
|
151
|
+
renewal fee. Both travel, under their own names.
|
|
152
|
+
|
|
153
|
+
Two more details that are only obvious once they have cost you an afternoon:
|
|
154
|
+
EDGAR's CIK must be zero-padded to ten digits or the submissions document is a
|
|
155
|
+
404 that reads like "this company does not file", and EDGAR's *former* names
|
|
156
|
+
are what turn a name disagreement into a rename rather than into two companies.
|
|
157
|
+
The comparison block reports the name agreement with its basis and flags when a
|
|
158
|
+
former name explains it.
|
|
159
|
+
|
|
160
|
+
An LEI's check digits are verified before dialling, because GLEIF answers 404
|
|
161
|
+
for a mistyped LEI and that 404 reads like "this company has no LEI record" —
|
|
162
|
+
a different and much more interesting claim.
|
|
163
|
+
|
|
164
|
+
## The VAT grammar is a table
|
|
165
|
+
|
|
166
|
+
A generic "two letters then eight to twelve characters" check passes ids that
|
|
167
|
+
VIES then rejects: the worst of both, a local check that gives false confidence
|
|
168
|
+
and a remote call that was avoidable. The awkward ones are why the table
|
|
169
|
+
exists — Ireland's letter in the *middle*, the Netherlands' B fixed in position
|
|
170
|
+
ten, Spain's letter-or-digit at each end, and Greece filing under `EL` while
|
|
171
|
+
its ISO code is `GR`.
|
|
172
|
+
|
|
173
|
+
Check digits are computed for the UK only, in both variants in circulation.
|
|
174
|
+
The other member states have their own algorithms; rather than write
|
|
175
|
+
twenty-seven from memory, this reports `passed: null` and says so. A checksum
|
|
176
|
+
that reports a pass for everything turns "we did not check" into "we checked
|
|
177
|
+
and it was fine".
|
|
178
|
+
|
|
179
|
+
## What this package does not do
|
|
180
|
+
|
|
181
|
+
- **It does not ingest the published lists.** OFAC, the UN, the EU and OFSI
|
|
182
|
+
publish XML and fixed-column CSV, in five different schemas with no shared
|
|
183
|
+
id. A hand-rolled parser that silently drops entries produces a short list
|
|
184
|
+
that looks complete, which is worse than no list — so this package parses
|
|
185
|
+
neither, and takes the snapshot above instead. If ingestion is wanted, the
|
|
186
|
+
parsers already exist as `@crewhaus/tool-data`'s `XmlParse` and `CsvParse`,
|
|
187
|
+
reachable the same way this package reaches `tool-text`; what it needs on top
|
|
188
|
+
is a recorded fixture per publisher, because a mis-read alias-quality field
|
|
189
|
+
reports a weak match as a strong one and nothing downstream can tell.
|
|
190
|
+
- **It reads two registers, not four.** Companies House and OpenCorporates need
|
|
191
|
+
an API key; GLEIF, EDGAR, VIES and HMRC do not, and no schema here accepts a
|
|
192
|
+
credential.
|
|
193
|
+
- **EDGAR by name covers listed filers only**, through EDGAR's own ticker map,
|
|
194
|
+
and each row says so. Not finding a company there is not evidence it does not
|
|
195
|
+
exist.
|
|
196
|
+
- **A failed read of an INDEX is never a negative.** EDGAR's ticker map and
|
|
197
|
+
GLEIF's legal-name search are things a lookup goes *through*, so a 404 on one
|
|
198
|
+
of them means the file moved and nothing was ever looked up —
|
|
199
|
+
`unavailable`, not "no such company". Only a 404 on a record URL (an LEI, a
|
|
200
|
+
CIK submissions document) is the register saying it holds no such record.
|
|
201
|
+
|
|
202
|
+
## Nothing here moves money
|
|
203
|
+
|
|
204
|
+
No schema accepts a bank credential, a card number, an account or an amount,
|
|
205
|
+
and `index.test.ts` asserts that over every schema in the package — recursing
|
|
206
|
+
into nested fields, and asserting its own hit count so that a scan which
|
|
207
|
+
matched nothing cannot pass as a clean result. The only bytes that leave the
|
|
208
|
+
process are an identifier going to a public register.
|
|
209
|
+
|
|
210
|
+
## Testing
|
|
211
|
+
|
|
212
|
+
The network seam is `_setKycFetch`. Every test drives it, and nothing in the
|
|
213
|
+
suite resolves a name or opens a socket — the SSRF check and the connect-time
|
|
214
|
+
IP pin live *below* the seam, in the default dialler, so a test never depends
|
|
215
|
+
on DNS. `SanctionsScreen` has no seam to drive, and a test asserts it never
|
|
216
|
+
reaches for one.
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import type { RegisteredTool } from "@crewhaus/tool-catalog";
|
|
2
|
+
export { _setKycFetch, type KycFetch, ORIGINS } from "./lib/net";
|
|
3
|
+
export declare const vatIdValidate: RegisteredTool;
|
|
4
|
+
export declare const entityRegistryLookup: RegisteredTool;
|
|
5
|
+
export declare const sanctionsScreen: RegisteredTool;
|
|
6
|
+
/** Every tool this package registers, in the order a catalog should list them. */
|
|
7
|
+
export declare const KYC_TOOLS: ReadonlyArray<RegisteredTool>;
|