@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 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.
@@ -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>;