@logicartisan/eid-bridge

TypeScript-client voor de Logicartisan eID-bridge — een lokale helper-app die de Belgische eID-kaart uitleest via een PC/SC-kaartlezer.

npm install @logicartisan/eid-bridge zod

Naast deze client heb je de bridge zelf nodig (de native binary + installer in eid-bridge/installers/dist/). Zonder de bridge geen verbinding met de kaartlezer.

Quickstart

import { pingBridge, readEidViaBridge } from "@logicartisan/eid-bridge";

// 1) Draait de bridge?
const health = await pingBridge();
if (!health) {
  alert("Installeer de eID-bridge eerst.");
  return;
}

// 2) Lees de eID uit, met live statusupdates.
const data = await readEidViaBridge((status) => {
  console.log("status:", status);
});

console.log(data.firstName, data.lastName, data.rrn);

Custom configuratie

import { createBridgeClient } from "@logicartisan/eid-bridge";

const bridge = createBridgeClient({
  httpUrl: "http://127.0.0.1:53195",   // default
  readTimeoutMs: 60_000,               // default 120_000
});
const data = await bridge.read();

Types

interface EidData {
  firstName?: string;
  middleName?: string;
  lastName?: string;
  dateOfBirth?: string;          // yyyy-MM-dd
  birthPlace?: string;
  gender?: "m" | "v" | "x";
  cardNumber?: string;
  nationality?: string;
  rrn?: string;                  // XX.XX.XX-XXX.XX
  photo?: string;                // data:image/jpeg;base64,...
  street?: string;
  houseNumber?: string;
  houseNumberAddition?: string;  // bus
  postalCode?: string;
  city?: string;
}

Server-side validatie

Wanneer je de data verder verstuurt naar je backend, valideer daar opnieuw — de bridge draait per slot op de pc van de eindgebruiker:

import { eidDataSchema, sanitizeEidPhoto } from "@logicartisan/eid-bridge";

// In je Next.js Server Action / API route:
const parsed = eidDataSchema.safeParse(input);
if (!parsed.success) throw new Error("ongeldige eID-data");

// Voor het foto-veld: extra check op data-URL-vorm + max-grootte
const safePhoto = sanitizeEidPhoto(parsed.data.photo);

Hulpmiddelen

splitBelgianStreet("Kerkstraat 12 bus 3") → { street, houseNumber, houseNumberAddition }

Browserondersteuning

• Chrome, Edge, Firefox, Safari (alles met native fetch + WebSocket).
• Node 22+ (native WebSocket en fetch).
• Node 18-21: polyfill globalThis.WebSocket zelf (bv. via ws).

Origin-allowlist

De bridge accepteert standaard requests vanaf:

• http://localhost:3636, http://127.0.0.1:3636 (Rijflow dev)
• http://rijflow.com, https://rijflow.com, https://www.rijflow.com
• http://localhost:3010, http://127.0.0.1:3010 (DiamondPos / juwelier-POS dev)
• https://portal.diamondpos.cloud, https://diamondpos.cloud

Onbekende origins krijgen automatisch een toestemming-prompt in de browser ("Eenmaal toestaan / Altijd toestaan / Weigeren") — geen rebuild nodig om nieuwe klanten toegang te geven.

Productie-domeinen toevoegen: start de bridge met --origin https://jouw-app.com.

Beveiliging

De bridge bindt op 127.0.0.1 (loopback-only) en doet:

• Host-headercontrole (anti-DNS-rebinding)
• CORS-allowlist + Origin-check
• Eenmalige 256-bit nonce per uitlezing

Voor het volledige bedreigingsmodel, zie SECURITY.md in de hoofd-repo.

Licentie

MIT — © Logicartisan.