nyilvantarto_scraper (Hungarian Government Registry)
Role
Interfaces with the Hungarian KKSZB (Kozponti Kormanyzati Szolgaltato Busz — Central Government Service Bus) to query official document registry data for identity verification. Active service (v2.0.4) with CI/CD.
| Property | Value |
|---|---|
| Version | 2.0.4 |
| Runtime | Node.js >= 20.15.0 |
| Author | Mihaly Pinter |
| CI | Travis CI |
| Queue | kkszb-rpc (RabbitMQ RPC) |
Architecture
graph LR vuer_oss[["[[vuer_oss]]"]] -->|RabbitMQ RPC<br/>kkszb-rpc| scraper[nyilvantarto_scraper] scraper -->|HTTPS<br/>Client Cert Auth| KKSZB[KKSZB<br/>Hungarian Gov API] scraper -->|OCSP| OCSP[Certificate<br/>Verification]
Supported Document Types
| Code | Document (Hungarian) | English |
|---|---|---|
| szig | Szemelyazonossagi igazolvany | Personal ID card |
| rszig | Regisztracios szemelyazonossagi igazolvany | Registration ID card |
| utl | Utlevel | Passport |
| ven | Vezetoi engedely | Driver’s license |
For each document type, the service supports:
| Query Type | Method |
|---|---|
| By 4T data | 4 personal attributes: name, birth date, mother’s name, birth place |
| By document ID | Direct document number lookup |
| Image retrieval | Face photo and signature image |
Key Files
| File | Role |
|---|---|
server.js | Entry point: connects to RabbitMQ nyilvantarto queue |
server/service/KkszbService.js | Main service: creates API config, processes queries |
server/kkszb/KkszbApi.js | HTTP/HTTPS client for KKSZB API calls |
server/kkszb/*QueryProcessor.js | Per-document-type request processors (8 total) |
server/kkszb/ImageJsonRequestProcessor.js | JSON-based image retrieval (szig, rszig) |
server/kkszb/ImageSoapRequestProcessor.js | SOAP-based image retrieval (utl, ven) |
server/kkszb/Context.js | Evidence collection context (zipped audit trail) |
server/util/certificate.js | OCSP verification for KKSZB TLS certificates |
server/util/request.js | HTTP/HTTPS request utilities |
bin/kkszbquery | CLI tool for manual KKSZB queries |
bin/qtspintegrity | CLI tool for QTSP integrity checks |
Query Processing
sequenceDiagram participant OSS as vuer_oss participant Scraper as nyilvantarto_scraper participant KKSZB as KKSZB (Gov API) OSS->>Scraper: RPC request (kkszb-rpc) Scraper->>Scraper: Select QueryProcessor by doc type Scraper->>Scraper: Create evidence Context Scraper->>KKSZB: HTTPS request (client cert auth) KKSZB-->>Scraper: Document data Scraper->>Scraper: OCSP verify server certificate Scraper->>Scraper: Log evidence (headers, payload, response) Scraper->>Scraper: Create evidence ZIP Scraper-->>OSS: Document data + images + evidence ZIP
Image Retrieval
Two different protocols depending on document type:
| Protocol | Document Types | Processor |
|---|---|---|
| JSON | szig, rszig | ImageJsonRequestProcessor |
| SOAP | utl, ven | ImageSoapRequestProcessor |
Evidence Collection (Legal Compliance)
Critical for Legal Compliance
Every query creates an evidence package (ZIP file) that is essential for legal compliance in government document verification.
Each evidence ZIP contains:
- Request headers (with sensitive data removed)
- Request payload
- Response headers
- Response data
- OCSP verification response
Security Features
| Feature | Details |
|---|---|
| TLS | CA certificate verification (configurable) |
| Client cert auth | Custom HTTPS agent with client certificates |
| OCSP | Certificate verification for KKSZB server certs |
| Evidence sanitization | Sensitive headers removed from evidence logs |
| Per-doc-type tokens | Separate API tokens per document type |
| Request tracing | crypto.randomUUID() for each request ID |
Container
| Property | Value |
|---|---|
| Compose file | services.yml |
| Base image | Custom with Node.js |
| Network | Host mode |
| Registry | harbor.techteamer.com |
Related
- vuer_oss — Backend that calls nyilvantarto via RPC
- FaceKom — Platform overview
- infrastructure — Container orchestration
- rabbitmq-communication — RPC patterns