@cyanheads/sanctions-screening-mcp-server 0.1.0

package/dist/services/screening/gleif-ingest.js

@@ -0,0 +1,251 @@
+/**
+ * @fileoverview GLEIF ingester — the heaviest leg. Resolves the latest
+ * golden-copy (full) or delta download URLs from the GLEIF Golden Copy API,
+ * streams the ZIP-compressed file, and normalizes LEI-CDF Level 1 (who-is-who)
+ * and RR-CDF Level 2 (who-owns-whom) records onto {@link NormalizedLeiEntity} /
+ * {@link NormalizedLeiRelationship}. Level 1 init is ~3.3M records / ~490 MB
+ * compressed (May 2026) — it runs out-of-band via `mirror:init`, never on the
+ * request path; refresh uses the 8-hour deltas keyed on a checkpoint.
+ *
+ * The normalization functions are the testable core (exercised by the synthetic
+ * fixture). The download/decompress wiring is documented and resilient; the real
+ * corpus loads out-of-band.
+ * @module services/screening/gleif-ingest
+ */
+import { gunzipSync, inflateRawSync } from 'node:zlib';
+import { serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+import { fetchWithTimeout, requestContextService, withRetry } from '@cyanheads/mcp-ts-core/utils';
+import { getServerConfig } from '../../config/server-config.js';
+import { parseXml } from '../../services/screening/xml.js';
+const FETCH_TIMEOUT_MS = 600_000;
+/** Coerce single-child→object / many→array (fast-xml-parser behavior). */
+function asArray(value) {
+    if (value == null)
+        return [];
+    return Array.isArray(value) ? value : [value];
+}
+function asText(value) {
+    if (value == null)
+        return;
+    if (typeof value === 'string')
+        return value.trim() || undefined;
+    if (typeof value === 'number')
+        return String(value);
+    if (typeof value === 'object' && '#text' in value) {
+        return asText(value['#text']);
+    }
+    return;
+}
+/**
+ * Conditional-spread fragment: `{ [key]: value }` when `value` is defined and
+ * non-empty, else `{}`. Keeps normalized objects honest under
+ * `exactOptionalPropertyTypes` without a non-null assertion.
+ */
+function opt(key, value) {
+    return value ? { [key]: value } : {};
+}
+/**
+ * Resolve the download URL for a GLEIF golden-copy or delta file. The Golden
+ * Copy API exposes a JSON index of the latest publications per file type and
+ * delta window; we read it and return the matching `.xml.gz` download link.
+ *
+ * @param kind Which dataset + window.
+ * @param delta Delta window when `kind` is a delta variant (e.g. `'LastDay'`, `'IntraDay'`).
+ */
+export async function resolveGleifFileUrl(kind, signal, delta = 'LastDay') {
+    const base = getServerConfig().gleifGoldenCopyBaseUrl.replace(/\/$/, '');
+    // GLEIF Golden Copy API publication index. The exact query shape:
+    //   /api/v2/golden-copies/publishes/lei2?format=xml  (full)
+    //   /api/v2/golden-copies/publishes/lei2/{window}     (delta)
+    const dataset = kind.startsWith('lei2') ? 'lei2' : 'rr';
+    const isDelta = kind.endsWith('delta');
+    const url = isDelta
+        ? `${base}/api/v2/golden-copies/publishes/${dataset}?delta.period=${delta}&format=xml`
+        : `${base}/api/v2/golden-copies/publishes/${dataset}?format=xml`;
+    const reqCtx = requestContextService.createRequestContext({ operation: `gleif:index:${kind}` });
+    const index = await withRetry(async () => {
+        const res = await fetchWithTimeout(url, 60_000, reqCtx, { signal });
+        return (await res.json());
+    }, { operation: `gleif:index:${kind}`, baseDelayMs: 2000, signal });
+    // The publication record carries a `data[].full_file.xml.url` (or delta_files).
+    const data = asArray((index.data ?? index))[0];
+    const fileNode = (isDelta ? data?.delta_files : data?.full_file);
+    const xmlNode = fileNode?.xml;
+    const downloadUrl = asText(xmlNode?.url) ?? asText(xmlNode?.download_link);
+    if (!downloadUrl) {
+        throw serviceUnavailable(`GLEIF Golden Copy index did not contain a download URL for ${kind}.`, { url });
+    }
+    return downloadUrl;
+}
+/**
+ * Download a GLEIF golden-copy / delta file and return the decompressed XML.
+ * The golden-copy downloads are **ZIP** containers (`PK\x03\x04`) wrapping a
+ * single XML entry — not gzip; the delta `.gz` files are gzip. Detection is by
+ * magic bytes (the URL suffix is unreliable behind the storage redirect), with a
+ * plain-XML fallback.
+ *
+ * NOTE (memory): this buffers and decompresses the whole file in memory. The
+ * Level 1 golden copy is ~3.3M records / ~900 MB compressed; decompressing and
+ * DOM-parsing it whole needs multiple GB of heap. A production `mirror:init`
+ * against the full L1 file requires a streaming ZIP → SAX pipeline; until then,
+ * real L1 ingest is bounded by available memory. Deltas and L2 are far smaller
+ * and fit comfortably.
+ */
+export function downloadGleifXml(url, signal) {
+    const reqCtx = requestContextService.createRequestContext({ operation: 'gleif:download' });
+    return withRetry(async () => {
+        const res = await fetchWithTimeout(url, FETCH_TIMEOUT_MS, reqCtx, { signal });
+        const buf = Buffer.from(await res.arrayBuffer());
+        const xml = decompressGleifBuffer(buf);
+        if (/^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(xml)) {
+            throw serviceUnavailable('GLEIF returned HTML instead of XML — likely rate-limited.');
+        }
+        return xml;
+    }, { operation: 'gleif:download', baseDelayMs: 3000, signal });
+}
+/** Decompress a downloaded GLEIF buffer by detecting ZIP / gzip / plain by magic bytes. */
+export function decompressGleifBuffer(buf) {
+    if (isZip(buf))
+        return extractFirstZipEntry(buf);
+    if (isGzip(buf))
+        return gunzipSync(buf).toString('utf8');
+    return buf.toString('utf8');
+}
+function isGzip(buf) {
+    return buf.length > 2 && buf[0] === 0x1f && buf[1] === 0x8b;
+}
+function isZip(buf) {
+    return buf.length > 4 && buf[0] === 0x50 && buf[1] === 0x4b && buf[2] === 0x03 && buf[3] === 0x04;
+}
+/**
+ * Extract the first file entry from a ZIP buffer (stored or deflate). GLEIF
+ * golden-copy ZIPs wrap exactly one XML file, so a single-entry reader is
+ * sufficient — it reads the local file header, then inflates the entry's raw
+ * deflate stream (or returns it verbatim when stored).
+ */
+export function extractFirstZipEntry(buf) {
+    // Local file header: sig(4)=PK\x03\x04, method@8(2), compressedSize@18(4),
+    // nameLen@26(2), extraLen@28(2), then [name][extra][data].
+    if (!isZip(buf) || buf.length < 30) {
+        throw serviceUnavailable('GLEIF download is not a valid ZIP archive.');
+    }
+    const method = buf.readUInt16LE(8);
+    let compressedSize = buf.readUInt32LE(18);
+    const nameLen = buf.readUInt16LE(26);
+    const extraLen = buf.readUInt16LE(28);
+    const dataStart = 30 + nameLen + extraLen;
+    // Streaming entries (general-purpose bit 3) report size 0 in the local header
+    // and place sizes in a trailing data descriptor; the entry data then runs up
+    // to the central-directory signature.
+    if (compressedSize === 0) {
+        const cd = buf.indexOf(Buffer.from([0x50, 0x4b, 0x01, 0x02]), dataStart);
+        compressedSize = (cd === -1 ? buf.length : cd) - dataStart;
+    }
+    const data = buf.subarray(dataStart, dataStart + compressedSize);
+    if (method === 0)
+        return data.toString('utf8');
+    if (method === 8)
+        return inflateRawSync(data).toString('utf8');
+    throw serviceUnavailable(`Unsupported ZIP compression method ${method} in GLEIF download.`);
+}
+/**
+ * Parse an LEI-CDF Level 1 XML document into normalized entity records. The
+ * record root is `<LEIRecords><LEIRecord>`; each carries an `<LEI>`, an
+ * `<Entity>` (legal name, other names, addresses, jurisdiction, status), and a
+ * `<Registration>` (registration status, last-update, RA).
+ */
+export function parseLeiLevel1(doc) {
+    const root = (doc.LEIData ?? doc['lei:LEIData'] ?? doc);
+    const records = asArray((root.LEIRecords ?? root['lei:LEIRecords'])
+        ?.LEIRecord ?? root.LEIRecords?.['lei:LEIRecord']);
+    return records
+        .map((raw) => parseOneLei(raw))
+        .filter(Boolean);
+}
+function parseOneLei(r) {
+    const lei = asText(r.LEI ?? r['lei:LEI']);
+    if (!lei)
+        return null;
+    const entity = (r.Entity ?? r['lei:Entity']);
+    const registration = (r.Registration ?? r['lei:Registration']);
+    const legalName = asText(entity?.LegalName?.['#text'] ?? entity?.LegalName) ?? 'Unknown';
+    const otherNames = asArray(entity?.OtherEntityNames?.OtherEntityName)
+        .map((n) => asText(n?.['#text'] ?? n))
+        .filter((x) => Boolean(x));
+    const legalAddr = renderAddress(entity?.LegalAddress);
+    const hqAddr = renderAddress(entity?.HeadquartersAddress);
+    const jurisdiction = asText(entity?.LegalJurisdiction);
+    const ra = entity?.RegistrationAuthority;
+    return {
+        lei,
+        legalName,
+        otherNames,
+        ...opt('jurisdiction', jurisdiction),
+        ...opt('status', asText(registration?.RegistrationStatus) ?? asText(entity?.EntityStatus)),
+        ...opt('legalAddress', legalAddr),
+        ...opt('headquartersAddress', hqAddr),
+        ...opt('registrationAuthorityId', asText(ra?.RegistrationAuthorityID)),
+        ...opt('registrationAuthorityEntityId', asText(ra?.RegistrationAuthorityEntityID)),
+        ...opt('lastUpdate', asText(registration?.LastUpdateDate)),
+    };
+}
+function renderAddress(addr) {
+    if (!addr)
+        return;
+    const parts = [
+        asText(addr.FirstAddressLine?.['#text'] ??
+            addr.FirstAddressLine),
+        asText(addr.AdditionalAddressLine),
+        asText(addr.City?.['#text'] ?? addr.City),
+        asText(addr.Region),
+        asText(addr.PostalCode),
+        asText(addr.Country?.['#text'] ?? addr.Country),
+    ].filter(Boolean);
+    return parts.length ? parts.join(', ') : undefined;
+}
+/**
+ * Parse an RR-CDF Level 2 XML document into normalized relationship records.
+ * The record root is `<RelationshipRecords><RelationshipRecord>`; each carries a
+ * `<Relationship>` with a start node (child), end node (parent), and type.
+ */
+export function parseLeiLevel2(doc) {
+    const root = (doc.RelationshipData ?? doc['rr:RelationshipData'] ?? doc);
+    const records = asArray((root.RelationshipRecords ?? root['rr:RelationshipRecords'])?.RelationshipRecord ??
+        root.RelationshipRecords?.['rr:RelationshipRecord']);
+    return records
+        .map((raw) => parseOneRelationship(raw))
+        .filter(Boolean);
+}
+function parseOneRelationship(r) {
+    const rel = (r.Relationship ?? r['rr:Relationship']);
+    if (!rel)
+        return null;
+    const startNode = (rel.StartNode ?? rel['rr:StartNode']);
+    const endNode = (rel.EndNode ?? rel['rr:EndNode']);
+    const childLei = asText(startNode?.NodeID ?? startNode?.['#text']);
+    const parentLei = asText(endNode?.NodeID ?? endNode?.['#text']);
+    const relationshipType = asText(rel.RelationshipType);
+    if (!childLei || !parentLei || !relationshipType)
+        return null;
+    const period = asArray(rel.RelationshipPeriods?.RelationshipPeriod)[0];
+    return {
+        childLei,
+        parentLei,
+        relationshipType,
+        ...opt('relationshipStatus', asText(rel.RelationshipStatus)),
+        ...opt('relationshipPeriod', asText(period?.StartDate)),
+    };
+}
+/** Fetch + decompress + parse Level 1 from a resolved URL. */
+export async function harvestLeiLevel1(url, signal) {
+    const xml = await downloadGleifXml(url, signal);
+    const doc = parseXml(xml);
+    return parseLeiLevel1(doc);
+}
+/** Fetch + decompress + parse Level 2 from a resolved URL. */
+export async function harvestLeiLevel2(url, signal) {
+    const xml = await downloadGleifXml(url, signal);
+    const doc = parseXml(xml);
+    return parseLeiLevel2(doc);
+}
+//# sourceMappingURL=gleif-ingest.js.map

package/dist/services/screening/gleif-ingest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gleif-ingest.js","sourceRoot":"","sources":["../../../src/services/screening/gleif-ingest.ts"],"names":[],"mappings":"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"}

package/dist/services/screening/sanctions-ingest.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Sanctions ingesters — one per source (OFAC SDN, OFAC
+ * Consolidated, EU FSF, UK Sanctions List, UN SC Consolidated). Each fetches the
+ * source file, parses the XML, and maps records onto the common
+ * {@link NormalizedDesignation} schema. The {@link createSanctionsSync} factory
+ * wires them into the MirrorService `sync` generator: each refresh re-harvests
+ * all sources in full (the combined corpus is tens of thousands of rows — no
+ * delta logic needed), yielding one page per source.
+ *
+ * The XML shapes differ wildly across sources; each parser is defensive about
+ * sparsity and arrays-of-one (fast-xml-parser collapses single children to
+ * objects), and preserves absence rather than fabricating fields.
+ * @module services/screening/sanctions-ingest
+ */
+import type { NormalizedDesignation, SourceCode } from '../../services/screening/types.js';
+/** A source ingester: yields a full set of normalized designations for one list. */
+export interface SanctionsIngester {
+    /** Fetch + parse + normalize the full list. */
+    harvest(signal: AbortSignal): Promise<NormalizedDesignation[]>;
+    source: SourceCode;
+    /** Source file URL (for provenance). */
+    url(): string;
+}
+export declare function parseOfac(doc: Record<string, unknown>, source: SourceCode): NormalizedDesignation[];
+export declare function parseEu(doc: Record<string, unknown>): NormalizedDesignation[];
+export declare function parseUk(doc: Record<string, unknown>): NormalizedDesignation[];
+export declare function parseUn(doc: Record<string, unknown>): NormalizedDesignation[];
+/** All five sanctions ingesters, configured from the current server config. */
+export declare function buildSanctionsIngesters(): SanctionsIngester[];
+/**
+ * The MirrorService `sync` generator for the sanctions designation mirror. Each
+ * run harvests every source in full and yields one page per source. The mirror
+ * upserts the `designation` rows; the per-alias `name` index is rebuilt from
+ * `designation.payload` after the sync by the service's `rebuildNameIndex()`
+ * (the lifecycle scripts and the refresh cron call it). `init` and `refresh`
+ * behave identically — these are small, fully re-harvested corpora.
+ */
+export declare function createSanctionsSync(): (ctx: {
+    signal: AbortSignal;
+}) => AsyncGenerator<{
+    records: Record<string, string | number | null>[];
+    checkpoint?: string;
+}>;
+/** Map a normalized designation to its primary-table row (no aux fields). */
+export declare function toDesignationRow(d: NormalizedDesignation): Record<string, string | number | null>;
+//# sourceMappingURL=sanctions-ingest.d.ts.map

package/dist/services/screening/sanctions-ingest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanctions-ingest.d.ts","sourceRoot":"","sources":["../../../src/services/screening/sanctions-ingest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAMV,qBAAqB,EACrB,UAAU,EACX,MAAM,+BAA+B,CAAC;AAGvC,oFAAoF;AACpF,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAAC;IAC/D,MAAM,EAAE,UAAU,CAAC;IACnB,wCAAwC;IACxC,GAAG,IAAI,MAAM,CAAC;CACf;AA6ED,wBAAgB,SAAS,CACvB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,MAAM,EAAE,UAAU,GACjB,qBAAqB,EAAE,CAiBzB;AAgYD,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,qBAAqB,EAAE,CA0D7E;AAsBD,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,qBAAqB,EAAE,CAyE7E;AAwBD,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,qBAAqB,EAAE,CAS7E;AAyED,+EAA+E;AAC/E,wBAAgB,uBAAuB,IAAI,iBAAiB,EAAE,CAS7D;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,KACL,KAAK;IAC/B,MAAM,EAAE,WAAW,CAAC;CACrB,KAAG,cAAc,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAY/F;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,CAajG"}