m2aadhil/open-iban repository overview

⁠open-iban Docker Image

TypeScript IBAN validation & BIC lookup service with web UI for bank data management. A modern port of fourcube/goiban⁠ that powers openiban.com.

⁠Features

✅ IBAN validation across 80+ countries (ISO 13616)
✅ BIC lookup for DE, AT, BE, NL, CH, LU, LI
✅ Calculate IBAN from country + bank code + account
✅ Admin web UI to upload/refresh bank register files
✅ Full audit trail with structured logging
✅ REST API compatible with openiban.com
✅ Prometheus metrics at /metrics

⁠Quick Start

docker run -d \
  -p 3000:3000 \
  -e JWT_SECRET=$(openssl rand -hex 32) \
  -v ./data:/app/data \
  --name open-iban \
  m2aadhil/open-iban:latest

Open http://localhost:3000⁠ for the API.

⁠Create admin user

docker exec -it open-iban node packages/server/dist/scripts/seedAdmin.js

Or set ADMIN_USERNAME and ADMIN_PASSWORD environment variables:

docker run -d \
  -p 3000:3000 \
  -e JWT_SECRET=$(openssl rand -hex 32) \
  -e ADMIN_USERNAME=admin \
  -e ADMIN_PASSWORD=supersecret \
  -v ./data:/app/data \
  m2aadhil/open-iban:latest

# Then run seed inside container
docker exec open-iban node packages/server/dist/scripts/seedAdmin.js

⁠API Endpoints

⁠Public (no auth)

• GET /validate/:iban?getBIC=true — validate + optional BIC lookup
• GET /calculate/:country/:bankCode/:account — build IBAN
• GET /countries — list supported countries
• GET /health — health check
• GET /metrics — Prometheus metrics

⁠Admin (JWT required)

• POST /admin/login — authenticate
• POST /admin/data/:country — upload bank register file
• GET /admin/data/status — data status per country
• GET /admin/audit — audit log

⁠Environment Variables

⁠Docker Compose

services:
  open-iban:
    image: m2aadhil/open-iban:latest
    ports:
      - "3000:3000"
    environment:
      JWT_SECRET: ${JWT_SECRET}
      NODE_ENV: production
    volumes:
      - ./data:/app/data
    restart: unless-stopped

Save as docker-compose.yml, then:

JWT_SECRET=$(openssl rand -hex 32) docker compose up -d

⁠Bank Data Sources

Upload official register files via the admin UI:

Download the file → Admin UI → Select country → Upload. Data is replaced atomically in a SQLite transaction.

⁠Architecture

React SPA (Vite + Tailwind)
       ↓
Fastify REST API (TypeScript)
       ↓
SQLite (WAL mode) + better-sqlite3
       ↓
7 country-specific parsers

⁠Volumes

• /app/data — SQLite DB + uploaded files (persist this!)

⁠Health Check

curl http://localhost:3000/health
# {"status":"ok","ts":"2026-05-19T..."}

⁠Example Usage

Validate an IBAN:

curl "http://localhost:3000/validate/DE89370400440532013000?getBIC=true"

Calculate an IBAN:

curl "http://localhost:3000/calculate/DE/37040044/0532013000"

Upload Bundesbank file (requires auth):

# First login to get cookie
curl -c cookies.txt -X POST http://localhost:3000/admin/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"supersecret"}'

# Upload file
curl -b cookies.txt -X POST http://localhost:3000/admin/data/DE \
  -F "[email protected]"

⁠What's Different from goiban?

✨ Enhancements:

• Web UI for data management (vs CLI-only)
• Full audit trail + structured logging
• Admin authentication + rate limiting
• Streaming file parsing (handles 100MB+ files)
• Atomic transactional data refresh
• Single binary deployment (no MySQL needed)
• TypeScript end-to-end
• Comprehensive test suite

⁠Security

• Argon2id password hashing
• JWT in httpOnly cookies
• Rate limiting (100/min public, 5/min login)
• IBAN PII hashing in audit logs
• Helmet security headers
• File upload size limits + extension validation

⁠License

MIT — same as the original goiban project.

⁠Links

• Source: https://github.com/m2aadhil/open-iban⁠
• Issues: https://github.com/m2aadhil/open-iban/issues⁠
• Original goiban: https://github.com/fourcube/goiban⁠
• Maintained by: @m2aadhil⁠